Documentation/lilypond
semantic.cache
.lock-wscript
+build/
@menu
* Introduction to contributing::
+* Quick start::
* Working with source code::
* Compiling::
* Documentation work::
@allowcodebreaks false
@include contributor/introduction.itexi
+@include contributor/quick-start.itexi
@include contributor/source-code.itexi
@include contributor/compiling.itexi
@include contributor/doc-work.itexi
@menu
* Help us::
* Overview of work flow::
-* Lilybuntu::
* Mentors::
@end menu
Git is a complex and powerful tool, but tends to be confusing at
first, particularly for users not familiar with the command line
-and/or version control systems. Contributors who don't want to
-deal with Git directly are encouraged to use the
-@command{lily-git} graphical user interface instead.
+and/or version control systems. We have created the
+@command{lily-git} graphical user interface to ease this
+difficulty.
@emph{Compiling} (@q{building}) LilyPond allows developers to see
how changes to the source code affect the program itself.
@uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}.
@warning{Contributors on Windows or MacOS X wishing to compile
-code or documentation are strongly advised to use @ref{Lilybuntu}
-instead of trying to install all software dependencies
-themselves.}
-
-
-@node Lilybuntu
-@section Lilybuntu
-
-It is not possible to compile LilyPond on Windows, and extremely
-difficulty to compile it on MacOS X. We have therefore made a
-@q{remix} of Ubuntu which includes all necessary dependencies to
-compile both LilyPond and the documentation. This can be run
-inside a virtual machine without disturbing your main operating
-system.
-
-@enumerate
-@item
-Install some virtualization software.
-
-Any virtualization tool can be used, but we recommend VirtualBox:
-
-@example
-@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
-@end example
-
-In virtualization terminology, your main operating system is the
-@qq{host}.
-
-@item
-Download the @file{lilybuntu2.iso} disk image:
-
-@example
-@uref{http://files.lilynet.net/lilybuntu2.iso}
-@end example
-
-@advanced{There is a md5sum available:
-@uref{http://files.lilynet.net/lilybuntu2.iso.md5}}
-
-@item
-Install @file{lilybuntu2.iso} as the @qq{guest} operating system
-on your virtualized system.
-
-@itemize
-
-@item
-If possible, use at least 700 MB of RAM (1GB would be better) for
-the virtual machine, and use @qq{dynamically expanding storage}
-for the virtual hard drive. A complete compile of everything
-(code, docs, regression tests) can reach 10 GB.
-
-@item
-When @file{lilybuntu2.iso} boots, it shows an ISOLINUX
-@code{boot:} prompt. Type:
-
-@example
-install
-@end example
-
-@item
-At the @qq{Prepare disk space} stage, do not be afraid to select
-@qq{Erase and use the entire disk}, since this refers to your
-@emph{virtual disk}, not your machine's actual hard drive.
-
-@item
-When prompted to remove the installation CD, go to
-@clicksequence{Devices @click{} CD/DVD Devices} and de-select
-@file{lilybuntu2.iso}.
-
-@end itemize
-
-@advanced{
-The latest version of lilybuntu is based on Ubuntu 10.04.1; if you
-encounter any difficulties installing it, search for one of the
-many tutorials for installing that particular version of Ubuntu as
-a guest operating system.
-}
-
-@item
-Do any extra configuration for your virtualization software.
-
-VirtualBox has extra @qq{guest additions} which can make the
-virtualization easier to use (full-screen, easy file sharing
-between host and guest operating systems, shared clipboards, etc).
-
-@enumerate
-
-@item
-In @emph{VirtualBox}, select @clicksequence{Devices @click{}
-Install Guest Additions...}.
-
-@item
-In @emph{Ubuntu}, select @clicksequence{Places @click{}
-VBOXADDITIONS_}. A file-system window will open.
-
-@item
-Double-click on the @file{autorun.sh} file, then select @qq{Run in
-Terminal}, and enter your password when prompted.
-
-@item
-Once the script is finished, restart Ubuntu to complete the
-installation.
-
-@item
-Set up any additional features, such as @q{Shared Folders} between
-your main operating system and ubuntu. Consult external
-documentation for this step.
-
-@advanced{If you do any kernel upgrades, you may need to re-run
-these VBOXADDITIONS instructions.}
-
-@end enumerate
-
-If you use other virtualization software, then follow the normal
-procedures for your virtualization software with Ubuntu as the
-client.
-
-@advanced{not all hardware is supported in all virtualization
-tools. In particular, some contributors have reported problems
-with USB devices. If you would like to investigate further, then
-look for help for your virtualization tool using your normal OS as
-the @qq{host} and Ubuntu as the @qq{client}.}
-
-@end enumerate
-
-If you are not familiar with Linux, it may be beneficial to read a
-couple of @qq{introduction to Ubuntu} webpages.
-
-@itemize
-@item
-One particular change from Windows and MacOS X is that most
-software should be installed with your @qq{package manager}; this
-vastly simplifies the process of installing and configuring
-software. Go to @clicksequence{System @click{} Administration
-@click{} Synaptic Package Manager}.
-
-@item
-The rest of this manual assumes that you are using the
-command-line; go to @clicksequence{Applications @click{}
-Accessories @click{} Terminal}.
-
-@end itemize
-
-You should now progress to @ref{Using lily-git}.
+code or documentation are strongly advised to use lilybuntu, as
+discussed in @ref{Quick start}.}
@node Mentors
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@node Quick start
+@chapter Quick start
+
+Want to submit a patch for LilyPond? Great! This chapter is
+designed to let you do this as quickly and easily as possible.
+
+It is not possible to compile LilyPond on Windows, and extremely
+difficulty to compile it on MacOS X. We have therefore made a
+@q{remix} of Ubuntu which includes all necessary dependencies to
+compile both LilyPond and the documentation. This can be run
+inside a virtual machine without disturbing your main operating
+system.
+
+@advanced{experienced developers may prefer to use their own
+development environment. It may be instructive to skim over these
+instructions, but be aware that this chapter is intended for
+helpful users who may have never created a patch before.}
+
+@menu
+* Lilybuntu::
+* Using lily-git::
+@end menu
+
+@node Lilybuntu
+@section Lilybuntu
+
+text.
+
+@menu
+* Installing lilybuntu::
+* Configuring lilybuntu in virtualbox::
+* Using lilybuntu::
+@end menu
+
+@node Installing lilybuntu
+@subsection Installing lilybuntu
+
+@enumerate
+@item
+Install some virtualization software.
+
+Any virtualization tool can be used, but we recommend VirtualBox:
+
+@example
+@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
+@end example
+
+In virtualization terminology, your main operating system is the
+@qq{host}, while lilybuntu is the @qq{guest}.
+
+@item
+Download the @file{lilybuntu2.iso} disk image: (approximately 1
+GB)
+
+@example
+@uref{http://files.lilynet.net/lilybuntu2.iso}
+@end example
+
+@advanced{There is a md5sum available:
+@uref{http://files.lilynet.net/lilybuntu2.iso.md5}}
+
+@item
+Install @file{lilybuntu2.iso} as the @qq{guest} operating system
+on your virtualized system.
+
+@itemize
+
+@item
+If possible, use at least 700 MB of RAM (1GB would be better) for
+the virtual machine, and use @qq{dynamically expanding storage}
+for the virtual hard drive. A complete compile of everything
+(code, docs, regression tests) can reach 10 GB.
+
+@item
+When @file{lilybuntu2.iso} boots, it shows an ISOLINUX
+@code{boot:} prompt. Type:
+
+@example
+install
+@end example
+
+@item
+At the @qq{Prepare disk space} stage, do not be afraid to select
+@qq{Erase and use the entire disk}, since this refers to your
+@emph{virtual disk}, not your machine's actual hard drive.
+
+@item
+When prompted to remove the installation CD, go to
+@clicksequence{Devices @click{} CD/DVD Devices} and de-select
+@file{lilybuntu2.iso}.
+
+@end itemize
+
+@advanced{
+The latest version of lilybuntu is based on Ubuntu 10.04.1; if you
+encounter any difficulties installing it, search for one of the
+many tutorials for installing that particular version of Ubuntu as
+a guest operating system.
+}
+
+@item
+Do any extra configuration for your virtualization software.
+
+We have additional instructions in
+@ref{Configuring lilybuntu in virtualbox}.
+
+If you use other virtualization software, then follow the normal
+procedures for your virtualization software with Ubuntu as the
+client.
+
+@advanced{not all hardware is supported in all virtualization
+tools. In particular, some contributors have reported problems
+with USB devices. If you would like to investigate further, then
+look for help for your virtualization tool using your normal OS as
+the @qq{host} and Ubuntu as the @qq{client}.}
+
+@end enumerate
+
+
+@node Configuring lilybuntu in virtualbox
+@subsection Configuring lilybuntu in virtualbox
+
+VirtualBox has extra @qq{guest additions} which can make the
+virtualization easier to use (full-screen, easy file sharing
+between host and guest operating systems, shared clipboards, etc).
+
+@enumerate
+
+@item
+In @emph{VirtualBox}, select @clicksequence{Devices @click{}
+Install Guest Additions...}.
+
+@item
+In @emph{Ubuntu}, select @clicksequence{Places @click{}
+VBOXADDITIONS_}. A file-system window will open.
+
+@item
+Double-click on the @file{autorun.sh} file, then select @qq{Run in
+Terminal}, and enter your password when prompted.
+
+@item
+Once the script is finished, restart Ubuntu to complete the
+installation.
+
+@item
+Set up any additional features, such as @q{Shared Folders} between
+your main operating system and ubuntu. Consult external
+documentation for this step.
+
+@advanced{If you do any kernel upgrades, you may need to re-run
+these VBOXADDITIONS instructions.}
+
+@end enumerate
+
+
+@node Using lilybuntu
+@subsection Using lilybuntu
+
+If you are not familiar with Linux, it may be beneficial to read a
+couple of @qq{introduction to Ubuntu} webpages.
+
+@itemize
+@item
+One particular change from Windows and MacOS X is that most
+software should be installed with your @qq{package manager}; this
+vastly simplifies the process of installing and configuring
+software. Go to @clicksequence{System @click{} Administration
+@click{} Synaptic Package Manager}.
+
+@item
+The rest of this manual assumes that you are using the
+command-line; go to @clicksequence{Applications @click{}
+Accessories @click{} Terminal}.
+
+@end itemize
+
+
+@c if you change this node name, you'll need to change the @ref in
+@c web/ and/or included/, along with all the translations.
+@node Using lily-git
+@section Using lily-git
+
+@command{lily-git.tcl} is a graphical tool to help you access and
+share changes to the lilypond source code.
+
+@menu
+* Install and configuration of lily-git.tcl::
+* Daily use of lily-git.tcl::
+@end menu
+
+@node Install and configuration of lily-git.tcl
+@unnumberedsubsec Install and configuration of @command{lily-git.tcl}
+
+@warning{The rest of this manual assumes that you are using the
+command-line; go to @clicksequence{Applications @click{}
+Accessories @click{} Terminal}.}
+
+@enumerate
+@item
+@code{lily-git.tcl} has already been install for you. Simply type
+(or copy&paste):
+
+@example
+cd
+wish lily-git.tcl
+@end example
+
+@item
+Click on the @qq{Get source} button.
+
+This will create a directory called @file{lilypond-git/} within
+your home directory, and will download the source code into that
+directory (around 55Mb). When the process is finished, the
+@qq{Command output} window will display @qq{Done}, and the button
+label will change to say @qq{Update source}.
+
+@item
+Navigate to the @file{lilypond-git/} directory to view the source
+files. You should now be able to modify the source files using
+your normal text editor.
+
+@end enumerate
+
+You should now progress to @ref{Compiling with lilybuntu}.
+
+@warning{Throughout the rest of this manual, most command-line
+input should be entered from @file{~/lilypond-git/}. This is
+referred to as the @emph{top source directory}.}
+
+
+@subsubheading Other operating music systems
+
+@enumerate
+@item
+If you haven't already, download and install Git.
+
+@itemize
+
+@item
+Lilybuntu users: git has already been installed for you.
+
+@item Windows users: download the @code{.exe} file labeled
+@qq{Full installer for official Git} from:
+
+@example
+@uref{http://code.google.com/p/msysgit/downloads/list}
+@end example
+
+@item Other operating systems: either install @command{git} with
+your package manager, or download it from the @qq{Binaries}
+section of:
+
+@example
+@uref{http://git-scm.com/download}
+@end example
+
+@end itemize
+
+
+@item
+Download the @command{lily-git.tcl} script from:
+
+@c don't change the cgit link below to gitweb; gitweb uses
+@c long filenames like "scripts_auxiliar_lily-git.tcl"
+
+@example
+@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
+@end example
+
+@item
+To run the program from the command line, navigate to the
+directory containing @command{lily-git.tcl} and enter:
+
+@example
+wish lily-git.tcl
+@end example
+
+@item
+Go read the lilybuntu instructions, starting from the @qq{get
+source} step.
+
+@end enumerate
+
+@advanced{the @qq{Get source} button does not fetch the entire
+history of the git repository, so utilities like @command{gitk}
+will only be able to display the most recent additions. As you
+continue to work with @command{lily-git.tcl}, the @qq{Update
+source} button will take any new additions and add it to whatever
+is currently in your repository's history.}
+
+
+@node Daily use of lily-git.tcl
+@unnumberedsubsec Daily use of @command{lily-git.tcl}
+
+@warning{Only work on one set of changes at once. Do not start
+work on any new changes until your first set has been accepted.}
+
+@subsubheading 1. Update source
+
+At the beginning of each session of lilypond work, you should
+click the @qq{Update source} button to get the latest changes to
+the source code.
+
+@warning{In some rare and unfortunate circumstances, this will
+result in a @emph{merge conflict}. If this occurs, follow the
+instructions for @qq{Abort changes}, below. Your work will not be
+lost.}
+
+
+@subsubheading 2a. New local commit
+
+A single commit typically represents one logical set of related
+changes (such as a bug-fix), and may incorporate changes to
+multiple files at the same time.
+
+When you're finished making the changes for a commit, click the
+@qq{New local commit} button. This will open the @qq{Git Commit
+Message} window. The message header is required, and the message
+body is optional.
+
+After entering a commit message, click @qq{OK} to finalize the
+commit.
+
+@advanced{for more information regarding commits and commit
+messages, see @ref{Commits and patches}.}
+
+
+@subsubheading 2b. Amend previous commit
+
+You can go back and make changes to the most recent commit with
+the @qq{Amend previous commit} button. This is useful if a
+mistake is found after you have clicked the @qq{New local commit}
+button.
+
+To amend the most recent commit, re-edit the source files as
+needed and then click the @qq{Amend previous commit} button. The
+earlier version of the commit is not saved, but is replaced by the
+new one.
+
+@warning{This does not update the patch @strong{files}; if you
+have a patch file from an earlier version of the commit, you will
+need to make another patch set when using this feature. The old
+patch file will not be saved, but will be replaced by the new one
+after you click on @qq{Make patch set}.}
+
+
+@subsubheading 3. Make patch set
+
+Before making a patch set from any commits, you should click the
+@qq{Update source} button to make sure the commits are based on
+the most recent remote snapshot.
+
+When you click the @qq{Make patch set} button,
+@command{lily-git.tcl} will produce patch files for any new
+commits, saving them to the current directory. The command output
+will display the name of the new patch files near the end of the
+output:
+
+@example
+0001-CG-add-lily-git-instructions.patch
+Done.
+@end example
+
+Send patch files to the appropriate place:
+
+@itemize
+@item
+If you have a mentor, send it to them via email.
+
+@item
+New contributors should send the patch attached to an email to
+@email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
+subject line.
+
+@item
+Translators should send patches to
+@email{translations@@lilynet.net}.
+
+@item
+More experienced contributors should upload the patch for
+web-based review. This requires additional software and use of
+the command-line; see @ref{Uploading a patch for review}.
+
+@end itemize
+
+
+@subsubheading The @qq{Abort changes -- Reset to origin} button
+
+@warning{Only use this if your local commit history gets
+hopelessly confused!}
+
+The button labeled @qq{Abort changes -- Reset to origin} will copy
+all changed files to a subdirectory of @file{lilypond-git/} named
+@file{aborted_edits/}, and will reset the repository to the
+current state of the remote repository (at @code{git.sv.gnu.org}).
+
+
+
+
@node Working with source code
@chapter Working with source code
-New contributors should only read @ref{Using lily-git}. Please
-ignore the rest of this chapter.
+@warning{New contributors should read @ref{Quick start}, and in
+particular @ref{Using lily-git}, instead of this chapter.}
-Advanced contributors will find the rest of this material quite
-useful, particularly if they are working on major new features.
+Advanced contributors will find this material quite useful,
+particularly if they are working on major new features.
@menu
-* Using lily-git::
* Starting with Git::
* Basic Git procedures::
* Advanced Git procedures::
@end menu
-@c if you change this node name, you'll need to change the @ref in
-@c web/ and/or included/, along with all the translations.
-@node Using lily-git
-@section Using lily-git
-
-@command{lily-git.tcl} is a graphical tool to help you access and
-share changes to the lilypond source code.
-
-@menu
-* Install and configuration of lily-git.tcl::
-* Daily use of lily-git.tcl::
-@end menu
-
-@node Install and configuration of lily-git.tcl
-@unnumberedsubsec Install and configuration of @command{lily-git.tcl}
-
-@subsubheading Lilybuntu
-
-@warning{The rest of this manual assumes that you are using the
-command-line; go to @clicksequence{Applications @click{}
-Accessories @click{} Terminal}.}
-
-@enumerate
-@item
-@code{lily-git.tcl} has already been install for you. Simply type
-(or copy&paste):
-
-@example
-cd
-wish lily-git.tcl
-@end example
-
-@item
-Click on the @qq{Get source} button.
-
-This will create a directory called @file{lilypond-git/} within
-your home directory, and will download the source code into that
-directory (around 55Mb). When the process is finished, the
-@qq{Command output} window will display @qq{Done}, and the button
-label will change to say @qq{Update source}.
-
-@item
-Navigate to the @file{lilypond-git/} directory to view the source
-files. You should now be able to modify the source files using
-your normal text editor.
-
-@end enumerate
-
-You should now progress to @ref{Compiling with lilybuntu}.
-
-@warning{Throughout the rest of this manual, most command-line
-input should be entered from @file{~/lilypond-git/}. This is
-referred to as the @emph{top source directory}.}
-
-
-@subsubheading Other operating music systems
-
-@enumerate
-@item
-If you haven't already, download and install Git.
-
-@itemize
-
-@item
-Lilybuntu users: git has already been installed for you.
-
-@item Windows users: download the @code{.exe} file labeled
-@qq{Full installer for official Git} from:
-
-@example
-@uref{http://code.google.com/p/msysgit/downloads/list}
-@end example
-
-@item Other operating systems: either install @command{git} with
-your package manager, or download it from the @qq{Binaries}
-section of:
-
-@example
-@uref{http://git-scm.com/download}
-@end example
-
-@end itemize
-
-
-@item
-Download the @command{lily-git.tcl} script from:
-
-@c don't change the cgit link below to gitweb; gitweb uses
-@c long filenames like "scripts_auxiliar_lily-git.tcl"
-
-@example
-@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
-@end example
-
-@item
-To run the program from the command line, navigate to the
-directory containing @command{lily-git.tcl} and enter:
-
-@example
-wish lily-git.tcl
-@end example
-
-@item
-Go read the lilybuntu instructions, starting from the @qq{get
-source} step.
-
-@end enumerate
-
-@advanced{the @qq{Get source} button does not fetch the entire
-history of the git repository, so utilities like @command{gitk}
-will only be able to display the most recent additions. As you
-continue to work with @command{lily-git.tcl}, the @qq{Update
-source} button will take any new additions and add it to whatever
-is currently in your repository's history.}
-
-
-@node Daily use of lily-git.tcl
-@unnumberedsubsec Daily use of @command{lily-git.tcl}
-
-@warning{Only work on one set of changes at once. Do not start
-work on any new changes until your first set has been accepted.}
-
-@subsubheading 1. Update source
-
-At the beginning of each session of lilypond work, you should
-click the @qq{Update source} button to get the latest changes to
-the source code.
-
-@warning{In some rare and unfortunate circumstances, this will
-result in a @emph{merge conflict}. If this occurs, follow the
-instructions for @qq{Abort changes}, below. Your work will not be
-lost.}
-
-
-@subsubheading 2a. New local commit
-
-A single commit typically represents one logical set of related
-changes (such as a bug-fix), and may incorporate changes to
-multiple files at the same time.
-
-When you're finished making the changes for a commit, click the
-@qq{New local commit} button. This will open the @qq{Git Commit
-Message} window. The message header is required, and the message
-body is optional.
-
-After entering a commit message, click @qq{OK} to finalize the
-commit.
-
-@advanced{for more information regarding commits and commit
-messages, see @ref{Commits and patches}.}
-
-
-@subsubheading 2b. Amend previous commit
-
-You can go back and make changes to the most recent commit with
-the @qq{Amend previous commit} button. This is useful if a
-mistake is found after you have clicked the @qq{New local commit}
-button.
-
-To amend the most recent commit, re-edit the source files as
-needed and then click the @qq{Amend previous commit} button. The
-earlier version of the commit is not saved, but is replaced by the
-new one.
-
-@warning{This does not update the patch @strong{files}; if you
-have a patch file from an earlier version of the commit, you will
-need to make another patch set when using this feature. The old
-patch file will not be saved, but will be replaced by the new one
-after you click on @qq{Make patch set}.}
-
-
-@subsubheading 3. Make patch set
-
-Before making a patch set from any commits, you should click the
-@qq{Update source} button to make sure the commits are based on
-the most recent remote snapshot.
-
-When you click the @qq{Make patch set} button,
-@command{lily-git.tcl} will produce patch files for any new
-commits, saving them to the current directory. The command output
-will display the name of the new patch files near the end of the
-output:
-
-@example
-0001-CG-add-lily-git-instructions.patch
-Done.
-@end example
-
-Send patch files to the appropriate place:
-
-@itemize
-@item
-If you have a mentor, send it to them via email.
-
-@item
-New contributors should send the patch attached to an email to
-@email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
-subject line.
-
-@item
-Translators should send patches to
-@email{translations@@lilynet.net}.
-
-@item
-More experienced contributors should upload the patch for
-web-based review. This requires additional software and use of
-the command-line; see @ref{Uploading a patch for review}.
-
-@end itemize
-
-
-@subsubheading The @qq{Abort changes -- Reset to origin} button
-
-@warning{Only use this if your local commit history gets
-hopelessly confused!}
-
-The button labeled @qq{Abort changes -- Reset to origin} will copy
-all changed files to a subdirectory of @file{lilypond-git/} named
-@file{aborted_edits/}, and will reset the repository to the
-current state of the remote repository (at @code{git.sv.gnu.org}).
-
-
@node Starting with Git
@section Starting with Git
-
Using the Git program directly (as opposed to using the
@command{lily-git.tcl} GUI) allows you to have much greater control
over the contributing process. You should consider using Git if
@warning{We suggest that contributors using Windows or MacOS X do
@strong{not} attempt to set up their own development environment;
-instead, use @rcontrib{Lilybuntu}.}
+instead, use lilybuntu as discussed in @rcontrib{Quick start}.}
Contributors using Linux or FreeBSD may also use Lilybuntu, but if
they prefer their own development environment, they should read
projects / lilypond.git / commitdiff