#########
### Rules
-$(outdir)/lilypond-%.info: $(outdir)/%.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi
+$(outdir)/lilypond-%.info: $(outdir)/%.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi $(outdir)/weblinks.itexi
$(MAKEINFO) -I$(src-dir) -I$(outdir) --output=$@ $<
# cd $(outdir) rule gets bit hairy for --srcdir configure builds
@end ignore
+@item
+A half-open articulation was added:
+@lilypond[quote,relative=2]
+c4\halfopen
+@end lilypond
+This is sometimes used to indicate half-open hi-hats.
+
@item
The Unicode Bidirectional Algorithm is now fully supported for
single-line markup due to enhanced integration with Pango.
@menu
* Introduction to contributing::
-* Starting with git::
+* Working with source code::
* Compiling LilyPond::
* Documentation work::
* Website work::
@include contributor/introduction.itexi
-@include contributor/git-starting.itexi
+@include contributor/working.itexi
@include contributor/compiling.itexi
@include contributor/doc-work.itexi
@include contributor/website-work.itexi
* Compiling from source::
* Concurrent Stable and Development Versions::
* Using a Virtual Machine to Compile LilyPond::
+* Build system::
@end menu
@node Compiling from source
You may install Lilypond using @code{make install}, or you may wish
to set up your system with concurrent stable and development
versions as described in the previous section.
+
+
+@node Build system
+@section Build system
+
+We currently use make and stepmake, which is complicated and only
+used by us. Hopefully this will change in the future.
+
+
+@subsubheading Version-specific texinfo macors
+
+@itemize
+
+@item
+made with @command{scripts/build/create-version-itexi.py} and
+@command{scripts/build/create-weblinks-itexi.py}
+
+@item
+used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
+website (made with website.make, used on lilypond.org)
+
+@item
+not (?) used in the main docs?
+
+@item
+the numbers in VERSION file: MINOR_VERSION should be 1 more than
+the last release, VERSION_DEVEL should be the last @strong{online}
+release. Yes, VERSION_DEVEL is less than VERSION.
+
+@end itemize
+
+
+
To organize multiple authors working on the documentation, we use a
Version Control System (VCS) called git, previously discussed in
-@ref{Starting with git}.
+@ref{Starting with Git}.
@menu
* Introduction to documentation work::
standard to follow.
@item
-Examples should end with a complete bar if possible.
+If possible, only write one bar per line.
@item
-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:
+If you only have one bar per line, omit bar checks. If you
+must put more than one bar per line (not recommended), then include bar
+checks.
+
+@item
+Tweaks should, if possible, also occur on their own line.
+Bad:
@example
\override textscript #'padding = #3 c1^"hi"
excepted in Templates, where `doctitle' may be omitted.
@item
-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)
+Avoid long stretches of input code. Nobody is going to read
+them in print. Create small examples. However, this does not mean
+it has be minimal.
@item
Specify durations for at least the first note of every bar.
but instead: \chordmode @{ c e g @}
@end example
-@item
-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.
-
@item
If you want to work on an example outside of the manual (for
easier/faster processing), use this header:
@itemize
@item
-Lines should be less than 72 characters long. (I personally
-recommend writing with 66-char lines, but don't bother modifying
-existing material.)
+Lines should be less than 72 characters long. (We personally
+recommend writing with 66-char lines, but do not bother modifying
+existing material).
@item
Do not use tabs.
@node Getting started with documentation translation
@subsection Getting started with documentation translation
-First, get the sources from the Git repository, see @ref{Documentation
-translations source code}.
+First, get the sources from the Git repository, see
+@ref{Downloading remote branches}.
@menu
* Translation requirements::
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 @ref{Sharing your
-changes}.
+this state of the sources easily if needed; see @ref{Making commits}.
@node Documentation translation details
+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-@node Starting with git
-@chapter 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 @ref{Other git documentation}.
-
-@menu
-* Getting the source code::
-* Updating the source code::
-* Sharing your changes::
-* Advanced git stuff::
-* Git on Windows::
-* Other git documentation::
-* Roadmap of directories::
-@end menu
-
-
-@node Getting the source code
-@section Getting the source code
-
-@menu
-* Git introduction::
-* Git user configuration::
-* Main source code::
-* Documentation translations source code::
-* Other branches::
-* Other locations for git::
-@end menu
-
-@node Git introduction
-@subsection 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 @ref{Updating the source code}.
-
-@warning{These instructions assume that you are using the
-command-line version of Git 1.5 or higher. Windows users should
-skip to @ref{Git on Windows}.}
-
-
-@node Git user configuration
-@subsection Git user configuration
-
-Some useful cofiguration can be performed automatically; cut and
-paste the following section:
-
-@example
-git config --global color.ui auto
-@end example
-
-To configure git to automatically use your name and email address
-for commits and patches, edit the below lines by changing all the
-@code{MY...} entries:
-
-@example
-git config --global user.name "MYNAME"
-git config --global user.email MYEMAIL@@EXAMPLE.NET
-@end example
-
-
-@node Main source code
-@subsection Main source code
-
-To get the main source code and documentation,
-
-@c WARNING: when updating the commands below, please
-@c update the other flavors in the two next nodes
-@c and in Introduction to Git concepts
-@smallexample
-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
-@end smallexample
-
-
-@node Documentation translations source code
-@subsection Documentation translations source code
-
-To translate the documentation,
-
-@smallexample
-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
-@end smallexample
-
-
-@node Other branches
-@subsection 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 @ref{Other git documentation}.
-
-@itemize
-
-@item @code{dev/XYZ}:
-These branches are for individual developers. They store code
-which is not yet stable enough to be added to the @code{master}
-branch.
-
-@item @code{stable/XYZ}:
-The branches are kept for archival reasons.
-
-@end itemize
-
-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
-@uref{http://lilypond.org/gub}. The git location is:
-
-@example
-http://github.com/janneke/gub
-@end example
-
-
-@node Other locations for git
-@subsection Other locations for git
-
-If you have difficulty connecting to most of the repositories
-listed in earlier sections, try:
-
-@example
-http://git.sv.gnu.org/r/lilypond.git
-git://git.sv.gnu.org/lilypond.git
-ssh://git.sv.gnu.org/srv/git/lilypond.git
-@end example
-
-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.
-
-
-
-@node Updating the source code
-@section Updating the source code
-
-@menu
-* Importance of updating::
-* Update command::
-* Resolving conflicts::
-@end menu
-
-
-@node Importance of updating
-@subsection 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 (@emph{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 @ref{Resolving conflicts}.
-
-
-@node Update command
-@subsection 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 @code{git.sv.gnu.org} repository:
-
-@example
-git pull -r
-@end example
-
-@noindent
-The @code{-r} option is short for @code{--rebase}. If you don't
-edit translated documentation and don't want to type @code{-r}
-every time, add @code{rebase = true} to the master branch in your
-@file{.git/config}, like so:
-
-@example
-[branch "master"]
- remote = origin
- merge = refs/heads/master
- rebase = true
-@end example
-
-@warning{translators and documentation editors, if you have
-changed committishes in the head of translated files using commits
-you have not yet pushed to @code{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 @code{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.}
-
-@c FIXME: when committishes automatic conditional update have been
-@c tested and documented, append the following to the warning above:
-@c Note that using update-committishes make target generally touches
-@c committishes.
-
-
-@node Resolving conflicts
-@subsection 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 @emph{How conflicts are presented} and @emph{How to
-resolve conflicts} in @command{git merge} man page.
-
-If all else fails, you can follow the instructions in
-@ref{Reverting all local changes}. Be aware that this eliminates
-any changes you have made!
-
-
-@node Sharing your changes
-@section Sharing your changes
-
-@menu
-* Producing a patch::
-* Committing directly::
-@end menu
-
-
-@node Producing a patch
-@subsection Producing a patch
-
-Once you have finished editing your files, checked that your changes
-meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
-set up your name and email in @ref{Git user configuration}, and
-checked that the entire thing compiles, you may:
-
-@example
-git commit -a
-git format-patch origin
-@end example
-
-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:
-
-@example
-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.
-@end example
-
-If the change is to the documentation only then the one-line
-summary should be prefixed with @qq{Docs: }.
-
-If you added a file to the source code, you must add it to git
-with:
-
-@example
-git add @var{FILENAME}
-@end example
-
-@noindent
-(and possibly modify the @file{GNUmakefile})
-
-These commands will produce one or more files named @file{0001-xyz},
-@file{0002-abc}, etc. in the top directory of the git tree. Send an
-email to @email{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
-@email{translations@@lilynet.net} instead.
-
-To check if you have correctly added any new files, use:
-
-@example
-git status
-@end example
-
-@noindent
-If this command lists any @emph{Changed but not updated} files,
-you should do a @command{git commit}. If it lists any
-@emph{Untracked files}, then you should do a @command{git add}.
-
-@seealso
-
-If your patch includes a significant amount of code, you may want to see
-@ref{Adding or modifying features}, especially @emph{Post patch for
-comments}.
-
-
-@node Committing directly
-@subsection 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 @ref{Git user
-configuration}, then edit @file{.git/config}: change the line
-
-@example
-url = git://git.sv.gnu.org/lilypond.git/
-@end example
-
-@noindent
-into
-
-@example
-url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
-@end example
-
-@noindent
-where @var{user} is your login name on Savannah.
-
-If you have not already done so, you should generate and upload a
-SSH key: open @uref{https://savannah.gnu.org/my/} in your browser,
-go to @q{Account Configuration}, then to something like
-@q{Edit SSH Keys}, and follow the instructions on that page.
-
-You may then:
-
-@example
-git push origin
-@end example
-
-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 @file{.git/config} that looks like
-this:
-
-@example
-[push]
- default = matching
-@end example
-
-@noindent
-Then @code{git push origin} will work as before. For more
-details, consult the @code{git push} man page.
-
-
-@node Advanced git stuff
-@section Advanced git stuff
-
-@warning{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 @code{lilypond/translation} and a stable branch,
-e.g. @code{stable/2.12}.
-
-Some Git commands are introduced first, then a workflow with several
-Git branches of LilyPond source code is presented.
-
-@menu
-* Introduction to Git concepts::
-* Git commands for managing several branches::
-* Working on LilyPond sources with several branches::
-* Git log::
-* Using local git branches::
-* Applying git patches::
-* Reverting all local changes::
-@end menu
-
-
-@node Introduction to Git concepts
-@subsection 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 @uref{http://book.git-scm.com/}.
-
-The @code{git pull origin} command above is just a shortcut for this
-command:
-
-@example
-git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
-@end example
-
-@noindent
-where @code{@var{branch}} is typically @code{master}, @code{web} or
-@code{lilypond/translation}; if you do not know or remember, see
-@ref{Getting the source code} to remember which commands you issued or
-which source code you wanted to get.
-
-A @emph{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 @emph{author} (the person who wrote the changes), the name and
-e-mail of the @emph{committer} (the person who brings these changes
-into the Git repository), and a commit message.
-
-A @emph{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 @emph{branch} is nothing more than a pointer to a particular commit,
-which is called the @emph{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 @ref{Getting the source code}.
-
-@example
-git remote add -f -t @var{branch} -m @var{branch} origin git://git.sv.gnu.org/lilypond.git/
-git checkout -b @var{branch} origin/@var{branch}
-@end example
-
-The @command{git remote} has created a branch called
-@code{origin/@var{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 @emph{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 @command{git pull origin} or @command{git fetch
-origin}.
-
-The @command{git checkout} command has created a branch named
-@code{@var{branch}}. At the beginning, this branch is identical to
-@code{origin/@var{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 @code{origin/@var{branch}} and @code{@var{branch}} since
-the last pulling. If you do not have push (i.e. @qq{write}) access on
-git.sv.gnu.org, your @code{@var{branch}} will always differ from
-@code{origin/@var{branch}}. In this case, remember that other people
-working like you with the remote branch @code{@var{branch}} of
-git://git.sv.gnu.org/lilypond.git/ (called @code{origin/@var{branch}}
-on your local repository) know nothing about your own
-@code{@var{branch}}: this means that whenever you use a committish or
-make a patch, others expect you to take the latest commit of
-@code{origin/@var{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.
-
-
-@node Git commands for managing several branches
-@subsection Git commands for managing several branches
-
-@subsubheading Listing branches and remotes
-
-You can get the exact path or URL of all remotes with
-running
-
-@example
-git remote -v
-@end example
-
-To list Git branches on your local repositories, run
-
-@example
-git branch # list local branches only
-git branch -r # list remote branches
-git branch -a # list all branches
-@end example
-
-
-@subsubheading 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
-
-@example
-git status
-@end example
-
-@noindent
-The currently checked out branch is also marked with an asterisk in
-the output of @command{git branch}.
-
-You can check out another branch @code{@var{other_branch}}, i.e. check
-out @code{@var{other_branch}} to the working tree, by running
-
-@example
-git checkout @var{other_branch}
-@end example
-
-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 @command{git status} to check
-this kind of issue before checking out another branch.
-
-
-@subsubheading Merging branches
-
-To merge branch @code{@var{foo}} into branch @code{@var{bar}}, i.e. to
-@qq{add} all changes made in branch @code{@var{foo}} to branch
-@code{@var{bar}}, run
-
-@example
-git checkout @var{bar}
-git merge @var{foo}
-@end example
-
-If any conflict happens, see @ref{Resolving conflicts}.
-
-There are common usage cases for merging: as a translator, you will
-often want to merge @code{master} into @code{lilypond/translation}; on
-the other hand, the Translations meister wants to merge
-@code{lilypond/translation} into @code{master} whenever he has checked
-that @code{lilypond/translation} builds successfully.
-
-
-@node Working on LilyPond sources with several branches
-@subsection Working on LilyPond sources with several branches
-
-@subsubheading Fetching new branches from git.sv.gnu.org
-
-To fetch and check out a new branch named @code{@var{branch}} on
-git.sv.gnu.org, run from top of the Git repository
-
-@example
-git config --add remote.origin.fetch +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
-git checkout --track -b @var{branch} origin/@var{branch}
-@end example
-
-After this, you can pull @code{@var{branch}} from git.sv.gnu.org with
-
-@example
-git pull origin
-@end example
-
-Note that this command generally fetches all branches you added with
-@command{git remote add} (when you initialized the repository) or
-@command{git config --add}, i.e. it updates all remote branches from
-remote @code{origin}, then it merges the remote branch tracked by
-current branch into current branch. For example, if your current
-branch is @code{master} --- which is the case if you got the sources
-with the commands described in @ref{Main source code} and did not
-issue any @command{git checkout} command --- @code{origin/master} will
-be merged into @code{master}.
-
-
-@subsubheading Local clones, or having several working trees
-
-If you play with several Git branches, e.g. @code{master},
-@code{lilypond/translation}, @code{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
-@code{@var{branch}}, run
-
-@example
-git checkout @var{branch}
-git clone -l -s -n . @var{subdir}
-cd @var{subdir}
-git reset --hard
-@end example
-
-Note that @code{@var{subdir}} must be a directory name which does not
-already exist. In @code{@var{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 @code{@var{subdir}} and run @command{git pull}; to send changes
-made on the subrepository back to the main repository, run
-@command{git push} from @code{@var{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 @code{@var{branch}} from @code{@var{subdir}} to the main
-repository, and @code{@var{branch}} is checked out in the main
-repository, you must save uncommitted changes (see @command{git
-stash}) and do @command{git reset --hard} in the main repository in
-order to apply pushed changes in the working tree of the main
-repository.
-
-
-@node Git log
-@subsection 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
-
-@example
-git log # only shows the logs (author, committish and commit message)
-git log -p # also shows diffs
-gitk # shows history graphically
-@end example
-
-@warning{The @code{gitk} command may require a separate @code{gitk} package,
-available in the appropriate distribution's repositories.}
-
-@node Using local git branches
-@subsection Using local git branches
-
-Branches can also be created for local document editing or code
-development. They permit the editor to work on several
-streams at once simply by switching between branches. The use of
-separate branches by code developers, who may be working on changes
-for an extended period, is essential.
-
-A branch based on the current state of master is created by
-checking out master and entering the command
-
-@example
-git branch @var{local-branch-name}
-@end example
-
-and deleted with the command
-
-@example
-git branch -d @var{local-branch-name}
-@end example
-
-The list of all branches can be obtained with
-
-@example
-git branch -a
-@end example
-
-and their relation to other branches may be seen with gitk.
-
-When all the changes you wish to make to a local branch are
-complete and committed you may merge them into master; see
-@ref{Git commands for managing several branches}. Alternatively
-individual commits may be cherry-picked from one branch to
-another. Gitk provides the easiest way of doing this.
-
-If your local copy of master has been updated since one of your
-local branches was created you may wish to insert the new commits
-in master @qq{underneath} your commits in your local branch. This
-is achieved with the rebase command:
-
-@example
-git rebase --whitespace=fix master @var{local-branch-name}
-@end example
-
-You should always update master and rebase your local branch in
-this way before generating a patch. It is also a convenient way
-of removing whitespace errors from your local edits before merging
-and pushing to origin/master.
-
-@node Applying git patches
-@subsection Applying git patches
-
-Well-formed git patches created with @code{git format-patch}
-should be committed with the following command:
-
-@example
-git am @var{patch}
-@end example
-
-Patches created without @code{git format-patch} can be applied in
-two steps. The first step is to apply the patch to the working
-tree:
-
-@example
-git apply @var{patch}
-@end example
-
-@noindent
-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:
-
-@example
-git commit -a --author="First Last <user@@example.net>"
-@end example
-
-
-@node Reverting all local changes
-@subsection 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:
-
-@example
-git reset --hard origin/master
-@end example
-
-
-@node Git on Windows
-@section Git on Windows
-
-@c Some of this may duplicate stuff in other sections
-@c But it is probably best for windows users to have it all together
-@c If necessary, clear this up later -td
-
-@subsection 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 @q{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 @q{checked out} local branch.
-
-Files are edited on a local branch, and in that state the
-changes are said to be @q{unstaged}. When editing is complete, the
-changes are moved to being @q{staged for commit}, and finally the
-changes are @q{committed} to the local branch. Once committed, the
-changes (called a @q{commit}) are given a unique 40-digit hexadecimal
-reference number called the @q{Committish} or @q{SHA1 ID} which
-identifies the commit to Git. Such committed changes can be sent to
-the master repository by @q{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 @q{diff} or @q{patch} (which send just
-the differences from the master repository).
-
-@subsection Installing git
-
-Obtain Git from
-@uref{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.
-
-@subsection 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 @code{[path]/Git}, but
-if you intend using Git for other projects a directory name like
-@code{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
-
-@example
-cd [path]/Git
-@end example
-
-to position the shell at your new Git repository.
-
-Note: if [path] contains folders with names containing
-spaces use
-
-@example
-cd "[path]/Git"
-@end example
-
-Then type
-
-@example
-git init
-@end example
-
-to initialize your Git repository.
-
-Then type (all on one line; the shell will wrap automatically)
-
-@example
-git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
-@end example
-
-to download the lilypond master files.
-
-@warning{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 @q{master} and we shall do that
-here.
-
-To do this, type
-
-@example
-git checkout -b master origin/master
-@end example
-
-This creates a second branch called @q{master}. You will see
-two warnings (ignore these), and a message advising you that
-your local branch @q{master} has been set up to track the remote
-branch. You now have two branches, a local branch called
-@q{master}, and a tracking branch called @q{origin/master},
-which is a shortened form of @q{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 @code{exit} or by
-clicking on the usual Windows close-window widget.
-
-@subsection 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
-
-@example
-cd [path]/Git
-git gui
-@end example
-
-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.
-
-@subsection Personalising your local git repository
-
-Open the Git GUI, click on
-
-@example
-Edit -> Options
-@end example
-
-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.
-
-@subsection Checking out a branch
-
-At this stage you have two branches in your local repository,
-both identical. To see them click on
-
-@example
-Branch -> Checkout
-@end example
-
-You should have one local branch called @q{master} and one
-tracking branch called @q{origin/master}. The latter is your
-local copy of the @q{remotes/origin/master} branch in the master
-LilyPond repository. The local @q{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.
-
-@subsection Updating files from @q{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
-
-@example
-Remote -> Fetch from -> origin
-@end example
-
-@noindent
-in the Git GUI.
-
-This will place the latest version of every file, including all the
-changes made by others, into the @q{origin/master} branch of the
-tracking branches in your git repository. You can see these files
-by checking out this branch, but you must @emph{never} edit any
-files while this branch is checked out. Check out your local
-@q{master} branch again.
-
-You then need to merge these fetched files into your local @q{master}
-branch by clicking on
-
-@example
-Merge -> Local Merge
-@end example
-
-@noindent
-and if necessary select the local @q{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 @q{master} branch to
-reflect the current state of the @q{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).
-
-@subsection Editing files
-
-First ensure your @q{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 @q{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
-
-@example
-Commit -> Amend Last Commit
-@end example
-
-@noindent
-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 @emph{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.
-
-
-@subsection Sending changes to @q{remotes/origin/master}
-
-If you do not have write access to @q{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
-
-@example
-cd [path]/Git
-@end example
-
-if necessary, then produce the patch with
-
-@example
-git format-patch origin
-@end example
-
-This will create a patch file for all the locally committed files
-which differ from @q{origin/master}. The patch file can be found
-in [path]/Git and will have a name formed from the commit
-message.
-
-@subsection Resolving merge conflicts
-
-As soon as you have committed a changed file your local @q{master}
-branch has diverged from @q{origin/master}, and will
-remain diverged until your changes have been committed
-in @q{remotes/origin/master} and Fetched back into your
-@q{origin/master} branch. Similarly, if a new commit has been made
-to @q{remotes/origin/master} by someone else and Fetched, your
-local @q{master} branch is divergent. You can detect a divergent
-branch by clicking on
-
-@example
-Repository -> Visualise all branch history
-@end example
-
-This opens up a very useful new window called @q{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 @q{master} tag on the same node as
-the @q{remotes/origin/master} tag your branch has diverged from
-@q{origin/master}. This is quite normal if files you have modified
-yourself have not yet been Pushed to @q{remotes/origin/master} and
-Fetched, or if files modified and committed by others have been
-Fetched since you last Merged @q{origin/master} into your local
-@q{master} branch.
-
-If a file being merged from @q{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 @q{remotes/origin/master}
-for you has added some changes of his own before
-committing your changes to @q{remotes/origin/master}, or if someone
-else has changed the same file since you last
-fetched the file from @q{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]
-
-
-@subsection Other actions
-
-The instructions above describe the simplest way of using
-git on Windows. Other git facilities which may usefully
-supplement these include
-
-@itemize
-
-@item Using multiple local branches (Create, Rename, Delete)
-@item Resetting branches
-@item Cherry-picking commits
-@item Pushing commits to @w{remote/origin/master}
-@item Using gitk to review history
-
-@end itemize
-
-Once familiarity with using git on Windows has been gained the
-standard git manuals can be used to learn about these.
-
-
-@node Other git documentation
-@section Other git documentation
-
-@itemize
-
-@item
-Official git man pages: @uref{http://www.kernel.org/pub/software/scm/git/docs/}
-
-@item
-More in-depth tutorials: @uref{http://git-scm.com/documentation}
-
-@item
-Book about git: @uref{http://progit.org/,Pro Git}
-
-@end itemize
-
-
-@node Roadmap of directories
-@section Roadmap of directories
-
-@c TODO: integrate the roadmap better
-@verbatiminclude ROADMAP
-
@item
Inform your mentor if you're willing to do more work -- we always
-have way more work than we have helpers available.
+have way more work than we have helpers available. We try to
+avoid overwhelming new contributors, so you'll be given less work
+than we think you can handle.
@end enumerate
@chapter Release work
@menu
-* Development phases::
-* Minor release checklist::
-* Major release checklist::
-* Release extra notes::
+* Development phases::
+* Minor release checklist::
+* Major release checklist::
+* Release extra notes::
+* Administrative policies::
@end menu
@enumerate
-@item Add a news item to @file{Documentation/web/news-front.itexi}
+@item
+switch to the release branch:
+
+@example
+git checkout release/unstable
+@end example
+
+@item
+Get latest changes:
-@item Check that lilypond builds from scratch in an out-of-tree
-build.
+@example
+git merge origin
+@end example
+
+@item
+Make a release announcement by adding a news item, and moving the
+oldest news item out of -front.
+
+@example
+Documentation/web/news-front.itexi
+Documentation/web/news.itexi
+@end example
+
+@item (optional) Check that lilypond builds from scratch in an
+out-of-tree build.
+
+@item Upload release branch.
+
+@example
+git push release/unstable
+@end example
@item
If you do not have the previous release test-output tarball, download
@example
make LILYPOND_BRANCH=stable/2.12 lilypond
+make LILYPOND_BRANCH=release/unstable lilypond
@end example
-
@item Check the regtest comparison in @file{uploads/webtest/} for
any unintentional breakage.
-@item Check if the mingw build contains lilypad.exe; when you find
-that it doesn't, rebuild @code{mingw::lilypond-installer}. Repeat
-as necessary.
-
-@uref{http://code.google.com/p/lilypond/issues/detail?id=901}
-
@item If any work was done on GUB since the last release, upload
binaries to a temporary location, ask for feedback, and wait a day
or two in case there's any major problems.
@end enumerate
-@subheading Post-release
+@subheading Actual release
@enumerate
make lilypond-upload LILYPOND_BRANCH=stable/2.12 LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git
@end example
+@end enumerate
+
+
+@subheading Post release
+
+@enumerate
+
+@item Switch back to master and get the updated news:
+
+@example
+git checkout master
+git merge release/unstable
+@end example
+
+@item Update @file{VERSION} in lilypond git:
+
+@example
+VERSION = what you just did +0.0.1
+DEVEL_VERSION = what you just did (i.e. is now online)
+STABLE_VERSION = what's online
+@end example
+
+@item Push changes.
+
+@item (for now) do a @code{make doc} and manually upload:
+
+@example
+### upload-lily-web-media.sh
+#!/bin/sh
+BUILD_DIR=$HOME/src/build-lilypond
-@item Update @file{VERSION} in lilypond git.
+PICS=$BUILD_DIR/Documentation/pictures/out-www/
+EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
+
+cd $BUILD_DIR
+rsync -a $PICS graham@@lilypond.org:media/pictures
+rsync -a $EXAMPLES graham@@lilypond.org:media/ly-examples
+@end example
@item Wait a few hours for the website to update.
@end enumerate
+
@node Major release checklist
@section Major release checklist
@node Release extra notes
@section Release extra notes
-If releasing stable/2.12, then:
+@subsubheading Regenerating regression tests
-- apply doc patch: patches/rsync-lily.patch (or something like
- that)
+Regenerating regtests (if the lilypond-book naming has changed):
-- change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
- to "lilypond-web.info"
+@itemize
+@item
+git checkout release/lilypond-X.Y.Z-A
-GENERAL STUFF TO BE MOVED ELSEWHERE
+@item
+take lilypond-book and any related makefile updates from the
+latest git.
-Regenerating regtests (if the lilypond-book naming has changed):
+@item
+- configure; make; make test
-- git checkout release/lilypond-X.Y.Z-A
+@item
+tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2 input/regression/out-test/
-- take lilypond-book and any related makefile updates from the
- latest git.
+@item
+mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
-- configure; make; make test
+@item
+cd ../gub/regtests/
-- tar -cjf lilypond-X.Y.Z-A.test-output.tar.bz2
- input/regression/out-test/
+@item
+make lilypond
-- mv lilypond-X.Y.Z-A.test-output.tar.bz2 ../gub/regtests/
+@end itemize
-- cd ../gub/regtests/
-- make lilypond
+@subsubheading stable/2.12
+If releasing stable/2.12, then:
-New contributor / mentor idea:
+@itemize
+
+@item
+apply doc patch: patches/rsync-lily.patch (or something like
+that)
+
+@item
+change infodir in gub/specs/lilypond-doc.py from "lilypond.info"
+to "lilypond-web.info"
+@end itemize
+
+@subsubheading Updating a release (changing a in x.y.z-a)
+
+Really tentative instructions, almost certainly can be done
+better.
+
+@enumerate
-- tell them to spend 10 minutes on a problem, then give up and ask
- for help from their mentor
+@item
+change the VERSION back to release you want. push change.
+(hopefully you'll have forgotten to update it when you made your
+last release)
-- the mentor should tell them if a "make clean; make" (or the same
- for docs) is required
+@item
+make sure that there aren't any lilypond files floating around in
+target/ (like usr/bin/lilypond).
+@item
+build the specific package(s) you want, i.e.
-Latest website:
+@example
+bin/gub mingw::lilypond-installer
+make LILYPOND_BRANCH=stable/2.12 -f lilypond.make doc
+bin/gub --platform=darwin-x86 'git://git.sv.gnu.org/lilypond-doc.git?branch=stable/2.12'
+@end example
+
+or
-- generated hourly on lilypond.org. Only split-HTML; big-html and
- pdf are not generated hourly (wait for the next devel release)
+build everything with the normal "make lilypond", then (maybe)
+manually delete stuff you don't want to upload.
+@item
+manually upload them. good luck figuring out the rsync
+command(s). Hints are in test-lily/
-VERSION-SPECIFIC MACROS
+or
-- made with scripts/build/create-version-itexi.py
+run the normal lilypond-upload command, and (maybe) manually
+delete stuff you didn't want to upload from the server.
-- used extensively in the WEBSITE_ONLY_BUILD version of the
- website (made with website.make, and used on lilypond.org)
+@end enumerate
-- not (?) used in the main docs?
-- FIXME: the numbers in VERSION: MINOR should be 1 more than the
- last release, VERSION_DEVEL should be the last *online* release.
+@node Administrative policies
+@section Administrative policies
+Not really release-specific notes, but I don't see enough material
+here to make it a separate chapter, and the release person will
+probably be the one taking care of this anyway.
-LANGUAGE LISTS
+@subsubheading Language-specific mailing lists
-- a translator can ask for an official lilypond-xy mailing list
- once they've finished all "priority 1" translation items.
+A translator can ask for an official lilypond-xy mailing list once
+they've finished all @qq{priority 1} translation items.
@node Uploading and security
@section Uploading and security
-FIXME: currently these are plans, not yet completely implemented.
-Hey, I'm doing the reponsible "write documentation first, then
-code" thing! I rock! -gp
-
The website is generated hourly by user @code{graham} the host
@code{lilypond.org}. For security reasons, we do not use the
makefiles and scripts directly from git; copies of the relevant
-scripts (below) are examined and copied to
-@file{~graham/trusted-scripts} on the host.
+scripts are examined and copied to
+@code{~graham/lilypond/trusted-scripts/}
+
+Get latest source code:
+
+@verbatim
+### update-git.sh
+#!/bin/sh
+cd $HOME/src/lilypond
+git fetch origin
+git merge origin/master
+@end verbatim
+
+Check for any updates to trusted scripts:
+
+@verbatim
+### check-git.sh
+#!/bin/sh
+GIT=$HOME/src/lilypond
+DEST=$HOME/lilypond/trusted-scripts
+diff -u $GIT/website.make $DEST/website.make
+diff -u $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
+diff -u $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
+diff -u $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
+diff -u $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
+@end verbatim
+
+If the changes look ok, make them trusted:
+
+@verbatim
+### copy-from-git.sh
+#!/bin/sh
+GIT=$HOME/src/lilypond
+DEST=$HOME/lilypond/trusted-scripts
+cp $GIT/website.make $DEST/website.make
+cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
+cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
+cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
+cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
+@end verbatim
+
+Build the website:
+
+@verbatim
+### make-website.sh
+#!/bin/sh
+DEST=$HOME/public_html/
+cd $HOME/src/build-website
+cp $HOME/lilypond/trusted-scripts/website.make .
+
+make -f website.make WEBSITE_ONLY_BUILD=1 website
+rsync -ra $HOME/src/build-website/out-website/website/ $DEST/website/
+cp $HOME/src/build-website/out-website/pictures $DEST
+@end verbatim
+
+Cronjob to automate the trusted portions:
+
+@verbatim
+# website-rebuild.cron
+11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
+22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
+@end verbatim
-@example
-website.make
-scripts/build/extract_texi_filenames.py
-@end example
To reduce the CPU burden on the shared host (as well as some
security concerns), the @file{Documentation/pictures/} and
@file{Documentation/web/ly-examples/} directories are @strong{not}
compiled. If you modify any files in those directories, a user in
the @code{lilypond} group must upload them to @file{~graham/media}
-on the host. This is done by running (locally) @code{make doc},
-followed by @code{scripts/build/upload-web-media.sh}.
+on the host.
+
+Upload latest pictures/ and ly-examples/ (local script):
+
+@verbatim
+### upload-lily-web-media.sh
+#!/bin/sh
+BUILD_DIR=$HOME/src/build-lilypond
+
+PICS=$BUILD_DIR/Documentation/pictures/out-www/
+EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
+cd $BUILD_DIR
+rsync -a $PICS graham@lilypond.org:media/pictures
+rsync -a $EXAMPLES graham@lilypond.org:ly-examples
+@end verbatim
@node Translating the website
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+
+@node Working with source code
+@chapter Working with source code
+
+
+@menu
+* Using lily-git::
+* Starting with Git::
+* Basic Git procedures::
+* Advanced Git procedures::
+* Git on Windows::
+* Repository directory structure::
+* Other Git documentation::
+@end menu
+
+
+@node Using lily-git
+@section Using lily-git
+
+
+FIXME: Add instructions for using @command{lily-git} here.
+
+
+@node Starting with Git
+@section Starting with Git
+
+
+Using the Git program directly (as opposed to using the
+@command{lily-git} GUI) allows you to have much greater control
+over the contributing process. You should consider using Git if
+you want to work on complex projects, or if you want to work on
+multiple projects concurrently.
+
+
+@menu
+* Setting up::
+* Downloading remote branches::
+@end menu
+
+
+@node Setting up
+@subsection Setting up
+
+
+FIXME: Remove this note if incorporating Windows instructions
+throughout this section:
+
+@warning{These instructions assume that you are using the
+command-line version of Git 1.5 or higher. Windows users should
+skip to @ref{Git on Windows}.}
+
+@menu
+* Installing Git::
+* Initializing a repository::
+* Configuring Git::
+@end menu
+
+
+@node Installing Git
+@unnumberedsubsubsec Installing Git
+
+
+If you are using a Unix-based machine, the easiest way to download
+and install Git is through a package manager such as @command{rpm}
+or @command{apt-get}---the installation is generally automatic.
+The only required package is (usually) called @command{git-core},
+although some of the auxiliary @command{git@var{*}} packages are
+also useful (such as @command{gitk}).
+
+Alternatively, you can visit the Git website
+(@uref{http://git-scm.com/}) for downloadable binaries and
+tarballs.
+
+FIXME: add Windows installation instructions (or @@ref@{Git on
+Windows@}).
+
+
+@node Initializing a repository
+@unnumberedsubsubsec Initializing a repository
+
+
+Once Git is installed, you'll need to create a new directory where
+your initial repository will be stored (the example below uses
+@file{~/lilypond-git/}, where @code{~} represents your home
+directory). Run @command{git@tie{}init} from within the new
+directory to initialize an empty repository:
+
+@example
+mkdir ~/lilypond-git/; cd ~/lilypond-git/
+git init
+@end example
+
+@subsubheading Technical details
+
+This creates (within the @file{~/lilypond-git/} directory) a
+subdirectory called @file{.git/}, which Git uses to keep track of
+changes to the repository, among other things. Normally you don't
+need to access it, but it's good to know it's there.
+
+
+@node Configuring Git
+@unnumberedsubsubsec Configuring Git
+
+@warning{Throughout the rest of this manual, all command-line
+input should be entered from the top directory of the Git
+repository being discussed (eg. @file{~/lilypond-git/}). This is
+referred to as a @emph{top source directory}.}
+
+Before downloading a copy of the main LilyPond repository, you
+should configure some basic settings with the
+@command{git@tie{}config} command. Git allows you to set both
+global and repository-specific options.
+
+To configure settings that affect all repositories, use the
+@command{--global} command line option. For example, the first
+two options that you should always set are your @var{name} and
+@var{email}, since Git needs these to keep track of commit
+authors:
+
+@example
+git config --global user.name "@var{John Smith}"
+git config --global user.email @var{john@@example.com}
+@end example
+
+To configure Git to use colored output where possible, use:
+
+@example
+git config --global color.ui auto
+@end example
+
+The text editor that opens when using @command{git@tie{}commit}
+can also be changed. If none of your editor-related environment
+variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
+editor is usually @command{vi} or @command{vim}. If you're not
+familiar with either of these, you should probably change the
+default to an editor that you know how to use. For example, to
+change the default editor to @command{nano}, enter:
+
+@example
+git config --global core.editor @var{nano}
+@end example
+
+FIXME: Add instructions for changing the editor on Windows, which
+is a little different, I think. -mp
+
+@subsubheading Technical details
+
+Git stores the information entered with
+@command{git@tie{}config@tie{}--global} in the file
+@file{.gitconfig}, located in your home directory. This file can
+also be modified directly, without using
+@command{git@tie{}config}. The @file{.gitconfig} file generated
+by the above commands would look like this:
+
+@example
+[user]
+ name = John Smith
+ email = john@@example.com
+[color]
+ ui = auto
+[core]
+ editor = nano
+@end example
+
+Using the @command{git@tie{}config} command @emph{without} the
+@command{--global} option configures repository-specific settings,
+which are stored in the file @file{.git/config}. This file is
+created when a repository is initialized (using
+@command{git@tie{}init}), and by default contains these lines:
+
+@example
+[core]
+ repositoryformatversion = 0
+ filemode = true
+ bare = false
+ logallrefupdates = true
+@end example
+
+However, since different repository-specific options are
+recommended for different development tasks, it is best to avoid
+setting any now. Specific recommendations will be mentioned later
+in this manual.
+
+
+@node Downloading remote branches
+@subsection Downloading remote branches
+
+
+@menu
+* Organization of remote branches::
+* LilyPond repository sources::
+* Downloading individual branches::
+* Downloading all remote branches::
+* Other branches::
+@end menu
+
+
+@node Organization of remote branches
+@unnumberedsubsubsec Organization of remote branches
+
+
+The main LilyPond repository is organized into @emph{branches} to
+facilitate development. These are often called @emph{remote}
+branches to distinguish them from @emph{local} branches you might
+create yourself (see @ref{Using local branches}).
+
+The @code{master} branch contains all the source files used to
+build LilyPond, which includes the program itself (both stable and
+development releases), the documentation (and its translations),
+and the website. Generally, the @code{master} branch is expected
+to compile successfully.
+
+The @code{lilypond/translation} branch is a side branch that
+allows translators to work without needing to worry about
+compilation problems. Periodically, the Translation Meister
+(after verifying that it doesn't break compilation), will
+@emph{merge} this branch back into @code{master} to incorporate
+recent translations. Similarly, the @code{master} branch is
+usually merged into the @code{lilypond/translation} branch after
+significant changes to the English documentation. See
+@ref{Translating the documentation} for details.
+
+
+@node LilyPond repository sources
+@unnumberedsubsubsec LilyPond repository sources
+
+
+The recommended source for downloading a copy of the main
+repository is:
+
+@example
+git://git.sv.gnu.org/lilypond.git
+@end example
+
+However, if your internet router filters out connections using the
+GIT protocol, or if you experience difficulty connecting via GIT,
+you can try these other sources:
+
+@example
+ssh://git.sv.gnu.org/srv/git/lilypond.git
+http://git.sv.gnu.org/r/lilypond.git
+@end example
+
+The SSH protocol can only be used if your system is properly set
+up to use it. Also, the HTTP protocol is slowest, so it should
+only be used as a last resort.
+
+
+@node Downloading individual branches
+@unnumberedsubsubsec Downloading individual branches
+
+
+Once you have initialized an empty Git repository on your system
+(see @ref{Initializing a repository}), you can download a remote
+branch into it. Make sure you know which branch you want to start
+with.
+
+To download the @code{master} branch, enter the following:
+
+@example
+git remote add -ft master -m master \
+ origin git://git.sv.gnu.org/lilypond.git/
+@end example
+
+To download the @code{lilypond/translation} branch, enter:
+
+@example
+git remote add -ft lilypond/translation -m \
+ lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
+@end example
+
+The @command{git@tie{}remote@tie{}add} process could take up to
+ten minutes, depending on the speed of your connection. The
+output will be something like this:
+
+@example
+Updating origin
+remote: Counting objects: 235967, done.
+remote: Compressing objects: 100% (42721/42721), done.
+remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
+Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
+Resolving deltas: 100% (195098/195098), done.
+From git://git.sv.gnu.org/lilypond
+ * [new branch] master -> origin/master
+From git://git.sv.gnu.org/lilypond
+ * [new tag] flower/1.0.1 -> flower/1.0.1
+ * [new tag] flower/1.0.10 -> flower/1.0.10
+â‹®
+ * [new tag] release/2.9.6 -> release/2.9.6
+ * [new tag] release/2.9.7 -> release/2.9.7
+@end example
+
+When @command{git@tie{}remote@tie{}add} is finished, the remote
+branch should be downloaded into your repository---though not yet
+in a form that you can use. In order to browse the source code
+files, you need to @emph{create} and @emph{checkout} your own
+local branch. In this case, however, it is easier to have Git
+create the branch automatically by using the @command{checkout}
+command on a non-existent branch. Enter the following:
+
+@example
+git checkout -b @var{branch} origin/@var{branch}
+@end example
+
+@noindent
+where @code{@var{branch}} is the name of your tracking branch,
+either @code{master} or @code{lilypond/translation}.
+
+Git will issue some warnings; this is normal:
+
+@example
+warning: You appear to be on a branch yet to be born.
+warning: Forcing checkout of origin/master.
+Branch master set up to track remote branch master from origin.
+Already on 'master'
+@end example
+
+By now the source files should be accessible---you should be able
+to edit any files in the @file{lilypond-git/} directory using a
+text editor of your choice. But don't start just yet! Before
+editing any source files, learn how to keep your changes organized
+and prevent problems later---read @ref{Basic Git procedures}.
+
+@subsubheading Technical Details
+
+The @command{git@tie{}remote@tie{}add} command should add some
+lines to your local repository's @file{.git/config} file:
+
+@example
+[remote "origin"]
+ url = git://git.sv.gnu.org/lilypond.git/
+ fetch = +refs/heads/master:refs/remotes/origin/master
+@end example
+
+
+@node Downloading all remote branches
+@unnumberedsubsubsec Downloading all remote branches
+
+
+To download all remote branches at once, you can @command{clone}
+the entire repository:
+
+@example
+git clone git://git.sv.gnu.org/lilypond.git
+@end example
+
+
+@node Other branches
+@unnumberedsubsubsec 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 @ref{Other Git documentation}.
+
+@itemize
+@item @code{dev/XYZ}:
+These branches are for individual developers. They store code
+which is not yet stable enough to be added to the @code{master}
+branch.
+
+@item @code{stable/XYZ}:
+The branches are kept for archival reasons.
+
+@end itemize
+
+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
+@uref{http://lilypond.org/gub}. The git location is
+@uref{http://github.com/janneke/gub}.
+
+
+@node Basic Git procedures
+@section Basic Git procedures
+
+
+@menu
+* The Git contributor's cycle::
+* Pulling and rebasing::
+* Using local branches::
+* Commits and patches::
+@end menu
+
+
+@node The Git contributor's cycle
+@subsection The Git contributor's cycle
+
+
+Here is a simplified view of the contribution process on Git:
+
+@enumerate
+@item
+Update your local repository by @emph{pulling} the most recent
+updates from the remote repository.
+
+@item
+Edit source files within your local repository's @emph{working
+directory}.
+
+@item
+@emph{Commit} the changes you've made to a local @emph{branch}.
+
+@item
+Generate a @emph{patch} to share your changes with the developers.
+@end enumerate
+
+
+@node Pulling and rebasing
+@subsection Pulling and rebasing
+
+
+When developers push new patches to the @code{git.sv.gnu.org}
+repository, your local repository is @strong{not} automatically
+updated. It is important to keep your repository up-to-date by
+periodically @emph{pulling} the most recent @emph{commits} from
+the remote branch. Developers expect patches to be as current as
+possible, since outdated patches require extra work before they
+can be used.
+
+Occasionally you may need to rework some of your own modifications
+to match changes made to the remote branch (see @ref{Resolving
+conflicts}), and it's considerably easier to rework things
+incrementally. If you don't update your repository along the way,
+you may have to spend a lot of time resolving branch conflicts and
+reconfiguring much of the work you've already done.
+
+Fortunately, Git is able to resolve certain types of branch
+conflicts automatically with a process called @emph{rebasing}.
+When rebasing, Git tries to modify your old commits so they appear
+as new commits (based on the latest updates). For a more involved
+explanation, see the @command{git-rebase} man page.
+
+To pull without rebasing (recommended for translators), use the
+following command:
+
+@example
+git pull # recommended for translators
+@end example
+
+If you're tracking the remote @code{master} branch, you should add
+the @code{-r} option (short for @code{--rebase}) to keep commits
+on your local branch current:
+
+@example
+git pull -r # use with caution when translating
+@end example
+
+If you don't edit translated documentation and don't want to type
+@code{-r} every time, configure the master branch to rebase by
+default with this command:
+
+@example
+git config branch.master.rebase true
+@end example
+
+FIXME: I think the next paragraph is confusing. Perhaps prepare
+the reader for new terms `committish' and `head'? -mp
+
+@warning{translators and documentation editors, if you have
+changed committishes in the head of translated files using commits
+you have not yet pushed to @code{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 @code{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.}
+
+FIXME: when committishes automatic conditional update have been
+tested and documented, append the following to the warning above:
+Note that using update-committishes make target generally touches
+committishes.
+
+@subsubheading Technical details
+
+The @command{git@tie{}config} command mentioned above adds the
+line @code{rebase = true} to the master branch in your local
+repository's @file{.git/config} file:
+
+@example
+[branch "master"]
+ remote = origin
+ merge = refs/heads/master
+ rebase = true
+@end example
+
+
+@node Using local branches
+@subsection Using local branches
+
+
+@menu
+* Creating and removing branches::
+* Listing branches and remotes::
+* Checking out branches::
+* Merging branches::
+@end menu
+
+
+@node Creating and removing branches
+@unnumberedsubsubsec Creating and removing branches
+
+
+Local branches are useful when you're working on several different
+projects concurrently. To create a new branch, enter:
+
+@example
+git branch @var{name}
+@end example
+
+To delete a branch, enter:
+
+@example
+git branch -d @var{name}
+@end example
+
+Git will ask you for confirmation if it sees that data would be
+lost by deleting the branch. Use @code{-D} instead of @code{-d}
+to bypass this. Note that you cannot delete a branch if it is
+currently checked out.
+
+
+@node Listing branches and remotes
+@unnumberedsubsubsec Listing branches and remotes
+
+You can get the exact path or URL of all remote branches by
+running:
+
+@example
+git remote -v
+@end example
+
+To list Git branches on your local repositories, run
+
+@example
+git branch # list local branches only
+git branch -r # list remote branches
+git branch -a # list all branches
+@end example
+
+
+@node Checking out branches
+@unnumberedsubsubsec 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
+
+@example
+git status
+@end example
+
+@noindent
+The currently checked out branch is also marked with an asterisk
+in the output of @command{git branch}.
+
+You can check out another branch @code{@var{other_branch}}, i.e.
+check out @code{@var{other_branch}} to the working tree, by
+running
+
+@example
+git checkout @var{other_branch}
+@end example
+
+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 @command{git status}
+to check this kind of issue before checking out another branch.
+
+@node Merging branches
+@unnumberedsubsubsec Merging branches
+
+To merge branch @code{@var{foo}} into branch @code{@var{bar}},
+i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
+branch @code{@var{bar}}, run
+
+@example
+git checkout @var{bar}
+git merge @var{foo}
+@end example
+
+If any conflict happens, see @ref{Resolving conflicts}.
+
+There are common usage cases for merging: as a translator, you
+will often want to merge @code{master} into
+@code{lilypond/translation}; on the other hand, the Translations
+meister wants to merge @code{lilypond/translation} into
+@code{master} whenever he has checked that
+@code{lilypond/translation} builds successfully.
+
+
+@node Commits and patches
+@subsection Commits and patches
+
+
+@menu
+* Understanding commits::
+* Making commits::
+* Commit messages::
+* Making patches::
+@end menu
+
+
+@node Understanding commits
+@unnumberedsubsubsec Understanding commits
+
+Technically, a @emph{commit} is a single point in the history of a
+branch, but most developers use the term to mean a @emph{commit
+object}, which stores information about a particular revision. A
+single commit can record changes to multiple source files, and
+typically represents one logical set of related changes (such as a
+bug-fix). You can list the ten most recent commits in your
+current branch with this command:
+
+@example
+git log -10 --oneline
+@end example
+
+If you're using an older version of Git and get an @q{unrecognized
+argument} error, use this instead:
+
+@example
+git log -10 --pretty=oneline --abbrev-commit
+@end example
+
+More interactive lists of the commits on the remote @code{master}
+branch are available at
+@uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
+@uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
+
+
+@node Making commits
+@unnumberedsubsubsec Making commits
+
+
+Once you have modified some source files in your working
+directory, you can make a commit with the following procedure:
+
+@enumerate
+@item
+Make sure you've configured Git properly (see @ref{Configuring
+Git}). Check that your changes meet the requirements described in
+@ref{Code style} and/or @ref{Documentation policy}. For advanced
+edits, you may also want to verify that the changes don't break
+the compilation process.
+
+@item
+Run the following command:
+
+@example
+git status
+@end example
+
+@noindent
+to make sure you're on the right branch, and to see which files
+have been modified, added or removed, etc. You may need to tell
+Git about any files you've added by running one of these:
+
+@example
+git add @var{file} # add untracked @var{file} individually
+git add . # add all untracked files in current directory
+@end example
+
+@noindent
+After @command{git@tie{}add}, run @command{git@tie{}status} again
+to make sure you got everything. You may also need to modify
+@file{GNUmakefile}.
+
+@item
+Preview the changes about to be committed (to make sure everything
+looks right) with:
+
+@example
+git diff HEAD
+@end example
+
+@noindent
+The @code{HEAD} argument refers to the most recent commit on the
+currently checked-out branch.
+
+@item
+Generate the commit with:
+
+@example
+git commit -a
+@end example
+
+@noindent
+The @code{-a} is short for @code{--all} which includes modified
+and deleted files, but only those newly created files that have
+previously been added.
+
+@end enumerate
+
+
+@node Commit messages
+@unnumberedsubsubsec Commit messages
+
+
+When you run the @command{git@tie{}commit@tie{}-a} command, Git
+automatically opens the default text editor so you can enter a
+@emph{commit message}. If you find yourself in a foreign editing
+environment, you're probably in @command{vi} or @command{vim}. If
+you want to switch to an editor you're more familiar with, quit by
+typing @code{:q!} and pressing @code{<Enter>}. See
+@ref{Configuring Git} for instructions on changing the default
+editor.
+
+In any case, Git will open a text file for your commit message
+that looks like this:
+
+@example
+
+# Please enter the commit message for your changes. Lines starting
+# with '#' will be ignored, and an empty message aborts the commit.
+# On branch master
+# Changes to be committed:
+# (use "git reset HEAD <file>..." to unstage)
+#
+# modified: working.itexi
+#
+@end example
+
+Your commit message should begin with a one-line summary
+describing the change (no more than 50 characters long), and if
+necessary a blank line followed by several lines giving the
+details:
+
+@c $ git log -1 --pretty=medium 4d6f1e5
+@example
+Doc: add Baerenreiter and Henle solo cello suites
+
+Added comparison of solo cello suite engravings to new essay with
+high-res images, fixed cropping on Finale example.
+@end example
+
+Commit messages often start with a short prefix describing the
+general location of the changes. If a commit affects the
+documentation in English (or in several languages simultaneously)
+the commit message should be prefixed with @qq{Doc:@tie{}}. If
+the commit affects only one of the translations, the commit
+message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
+@var{**} is the two-letter language code. Commits that affect the
+website should use @qq{Web:@tie{}} for English, and
+@qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
+to a single file are often prefixed with the name of the file
+involved. Visit the links listed in @ref{Understanding commits}
+for examples.
+
+
+@node Making patches
+@unnumberedsubsubsec Making patches
+
+
+If you want to share your changes with other contributors and
+developers, you need to generate @emph{patches} from your commits.
+You should always run @command{git@tie{}pull@tie{}-r} (translators
+should leave off the @code{-r}) before doing this to ensure that
+your patches are as current as possible.
+
+Once you have made one or more commits in your local repository,
+and pulled the most recent commits from the remote branch, you can
+generate patches from your local commits with the command:
+
+@example
+git format-patch origin
+@end example
+
+The @code{origin} argument refers to the remote tracking branch at
+@code{git.sv.gnu.org}. This command generates a separate patch
+for each commit that's in the current branch but not in the remote
+branch. Patches are placed in the current working directory and
+will have names that look something like this:
+
+@example
+0001-Doc-Fix-typos.patch
+0002-Web-Remove-dead-links.patch
+â‹®
+@end example
+
+Send an email to @email{lilypond-devel@@gnu.org} briefly
+explaining your work, with the patch files attached. Translators
+should send patches to @email{translations@@lilynet.net}. After
+your patches are reviewed, the developers may push one or more of
+them to the main repository or discuss them with you.
+
+@seealso
+
+If your patch includes a significant amount of code, you may want
+to see @ref{Adding or modifying features}, especially @emph{Post
+patch for comments}.
+
+
+@node Advanced Git procedures
+@section Advanced Git procedures
+
+
+@warning{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 @code{lilypond/translation} and a stable branch,
+e.g. @code{stable/2.12}.
+
+Some Git commands are introduced first, then a workflow with
+several Git branches of LilyPond source code is presented.
+
+
+@menu
+* Advanced Git concepts::
+* Resolving conflicts::
+* Reverting all local changes::
+* Working with remote branches::
+* Git log::
+* Applying remote patches::
+* Sending and receiving patches via email::
+* Commit access::
+@end menu
+
+
+@node Advanced Git concepts
+@subsection Advanced Git concepts
+
+
+A bit of Git vocabulary will be explained below. The following is
+only introductory; for a better understanding of Git concepts, you
+may wish to read @ref{Other Git documentation}.
+
+The @code{git@tie{}pull@tie{}origin} command above is just a
+shortcut for this command:
+
+@example
+git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
+@end example
+
+@noindent
+where @code{@var{branch}} is typically @code{master} or
+@code{lilypond/translation}; if you do not know or remember, see
+@ref{Downloading remote branches} to remember which commands you
+issued or which source code you wanted to get.
+
+A @emph{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 @emph{author} (the person who wrote the changes), the name
+and e-mail of the @emph{committer} (the person who brings these
+changes into the Git repository), and a commit message.
+
+A @emph{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 @emph{branch} is nothing more than a pointer to a particular
+commit, which is called the @emph{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 @ref{Downloading individual branches}.
+
+@example
+git remote add -ft @var{branch} -m @var{branch} \
+ origin git://git.sv.gnu.org/lilypond.git/
+
+git checkout -b @var{branch} origin/@var{branch}
+@end example
+
+The @command{git@tie{}remote} has created a branch called
+@code{origin/@var{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 @emph{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
+@command{git@tie{}pull@tie{}origin} or
+@command{git@tie{}fetch@tie{}origin}.
+
+The @command{git@tie{}checkout} command has created a branch named
+@code{@var{branch}}. At the beginning, this branch is identical
+to @code{origin/@var{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 @code{origin/@var{branch}} and
+@code{@var{branch}} since the last pulling. If you do not have
+push (i.e. @qq{write}) access on git.sv.gnu.org, your
+@code{@var{branch}} will always differ from
+@code{origin/@var{branch}}. In this case, remember that other
+people working like you with the remote branch @code{@var{branch}}
+of git://git.sv.gnu.org/lilypond.git/ (called
+@code{origin/@var{branch}} on your local repository) know nothing
+about your own @code{@var{branch}}: this means that whenever you
+use a committish or make a patch, others expect you to take the
+latest commit of @code{origin/@var{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.
+
+
+@node Resolving conflicts
+@subsection 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 @emph{How conflicts are presented} and
+@emph{How to resolve conflicts} in @command{git merge} man page.
+
+If all else fails, you can follow the instructions in
+@ref{Reverting all local changes}. Be aware that this eliminates
+any changes you have made!
+
+
+@node Reverting all local changes
+@subsection 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:
+
+@example
+git reset --hard origin/master
+@end example
+
+
+@node Working with remote branches
+@subsection Working with remote branches
+
+
+@subsubheading Fetching new branches from git.sv.gnu.org
+
+To fetch and check out a new branch named @code{@var{branch}} on
+git.sv.gnu.org, run from top of the Git repository
+
+@example
+git config --add remote.origin.fetch \
+ +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
+
+git checkout --track -b @var{branch} origin/@var{branch}
+@end example
+
+After this, you can pull @code{@var{branch}} from git.sv.gnu.org
+with:
+
+@example
+git pull
+@end example
+
+Note that this command generally fetches all branches you added
+with @command{git@tie{}remote@tie{}add} (when you initialized the
+repository) or @command{git@tie{}config@tie{}--add}, i.e. it
+updates all remote branches from remote @code{origin}, then it
+merges the remote branch tracked by the current branch into the
+current branch. For example, if your current branch is
+@code{master}, @code{origin/master} will be merged into
+@code{master}.
+
+
+@subsubheading Local clones, or having several working trees
+
+If you play with several Git branches, e.g. @code{master},
+@code{lilypond/translation}, @code{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 @code{@var{branch}}, run
+
+@example
+git checkout @var{branch}
+git clone -lsn . @var{subdir}
+cd @var{subdir}
+git reset --hard
+@end example
+
+Note that @code{@var{subdir}} must be a directory name which does
+not already exist. In @code{@var{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 @code{@var{subdir}} and run
+@command{git@tie{}pull}; to send changes made on the subrepository
+back to the main repository, run @command{git@tie{}push} from
+@code{@var{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 @code{@var{branch}} from @code{@var{subdir}} to the
+main repository, and @code{@var{branch}} is checked out in the
+main repository, you must save uncommitted changes (see
+@command{git@tie{}stash}) and do
+@command{git@tie{}reset@tie{}--hard} in the main repository in
+order to apply pushed changes in the working tree of the main
+repository.
+
+
+@node Git log
+@subsection 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
+@file{.git} directory. You can browse this history with
+
+@example
+git log # only shows the logs (author, committish and commit message)
+git log -p # also shows diffs
+gitk # shows history graphically
+@end example
+
+@warning{The @code{gitk} command may require a separate
+@code{gitk} package, available in the appropriate distribution's
+repositories.}
+
+
+@node Applying remote patches
+@subsection Applying remote patches
+
+
+FIXME: Explain how to determine if a patch was created with
+@code{git@tie{}format-patch}.
+
+Well-formed git patches created with @code{git@tie{}format-patch}
+should be committed with the following command:
+
+@example
+git am @var{patch}
+@end example
+
+Patches created without @code{git@tie{}format-patch} can be
+applied in two steps. The first step is to apply the patch to the
+working tree:
+
+@example
+git apply @var{patch}
+@end example
+
+@noindent
+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:
+
+@example
+git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
+@end example
+
+
+@node Sending and receiving patches via email
+@subsection Sending and receiving patches via email
+
+
+The default @code{x-diff} MIME type associated with patch files
+(i.e., files whose name ends in @code{.patch}) means that the
+encoding of line endings may be changed from UNIX to DOS format
+when they are sent as attachments. Attempting to apply such an
+inadvertently altered patch will cause git to fail with a message
+about @q{whitespace errors}.
+
+The solution to such problems is surprisingly simple---just change
+the default file extension of patches generated by git to end in
+@code{.txt}, for example:
+
+@example
+git config format.suffix '.patch.txt'
+@end example
+
+This should cause email programs to apply the correct base64
+encoding to attached patches.
+
+If you receive a patch with DOS instead of UNIX line-endings, it
+can be converted back using the @code{dos2unix} utility.
+
+Lots of useful information on email complications with patches is
+provided on the Wine wiki at
+@uref{http://wiki.winehq.org/GitWine}.
+
+
+@node Commit access
+@subsection Commit access
+
+
+Most contributors are not able to commit patches directly to the
+main repository---only members of the LilyPond development team
+have @emph{commit access}. If you are a contributor and are
+interested in joining the development team, contact the Project
+Manager through the mailing list
+(@email{lilypond-devel@@gnu.org}). Generally, only contributors
+who have already provided a number of patches which have been
+pushed to the main repository will be considered for membership.
+
+If you have been approved by the Project Manager, use the
+following procedure to obtain commit access:
+
+@enumerate
+@item
+If you don't already have one, set up a Savannah user account at
+@uref{https://savannah.gnu.org/account/register.php}. If your web
+browser responds with an @qq{untrusted connection} message when
+you visit the link, follow the steps for including the CAcert root
+certificate in your browser, given at
+@uref{http://savannah.gnu.org/tls/tutorial/}.
+
+@item
+After registering, if you are not logged in automatically, login
+at @uref{https://savannah.gnu.org/account/login.php}---this should
+take you to your @qq{my} page
+(@uref{https://savannah.gnu.org/my/}).
+
+@item
+Click on the @qq{My Groups} link to access the @qq{My Group
+Membership} page. From there, find the @qq{Request for Inclusion}
+box and search for @qq{LilyPond}. Among the search results, check
+the box labeled @qq{GNU LilyPond Music Typesetter} and write a
+brief (required) message for the Project Manager (@qq{Hey it's
+me!} should be fine).
+
+Note that you will not have commit access until the Project
+Manager activates your membership. Once your membership is
+activated, LilyPond should appear under the heading @qq{Groups I'm
+Contributor of} on your @qq{My Group Membership} page.
+
+@item
+Go to the @qq{My Account Configuration} page. From there, click
+on @qq{Edit SSH Keys} and follow the instructions given.
+
+FIXME: Explain the confusing warning I always get. -mp
+
+FIXME: Maybe add a note about enabling/disabling SSH passphrase?
+
+@item
+Configure Git to use the SSH protocol (instead of the GIT
+protocol). From your local Git repository, enter:
+
+@example
+git config remote.origin.url \
+ ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
+@end example
+
+@noindent
+where @var{user} is your username on Savannah.
+
+@item
+After your membership has been activated and you've configured Git
+to use SSH, try doing a @command{git@tie{}pull} or
+@command{git@tie{}pull@tie{}-r}. If that succeeds, this indicates
+that your SSH key stored at Savannah is working properly.
+
+FIXME: show what success/failure look like.
+
+@item
+Test your commit access with a dry run:
+
+@example
+git push --dry-run --verbose
+@end example
+
+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 tell Git to push all matching branches by default:
+
+@example
+git config push.default matching
+@end example
+
+@noindent
+Then @code{git@tie{}push} should work as before. For more
+details, consult the @code{git@tie{}push} man page.
+@end enumerate
+
+
+@subsubheading Technical details
+
+@itemize
+@item
+On Firefox, to view or remove the CAcert root certificate, go to:
+Edit > Preferences > Advanced > Encryption > View Certificates >
+Authorities > Certificate Name > Root CA > CA Cert Signing
+Authority.
+
+@item
+The @command{git@tie{}config} commands above should modify your
+local repository's @file{.git/config} file. These lines:
+
+@example
+[remote "origin"]
+ url = git://git.sv.gnu.org/lilypond.git/
+@end example
+
+@noindent
+should now be changed to:
+
+@example
+[remote "origin"]
+ url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
+@end example
+
+@noindent
+where @var{user} is your login name on Savannah.
+
+@item
+Similarly, the
+@command{git@tie{}config@tie{}push.default@tie{}matching} command
+should add these lines to @file{.git/config}:
+
+@example
+[push]
+ default = matching
+@end example
+@end itemize
+
+@node Git on Windows
+@section Git on Windows
+
+@c Some of this may duplicate stuff in other sections
+@c But it is probably best for windows users to have it all together
+@c If necessary, clear this up later -td
+
+FIXME: Decide what to do with this... Pare it down? Move
+paragraphs next to analogous Unix instructions? -mp
+
+@subsection 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 @q{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 @q{checked out} local branch.
+
+Files are edited on a local branch, and in that state the changes
+are said to be @q{unstaged}. When editing is complete, the
+changes are moved to being @q{staged for commit}, and finally the
+changes are @q{committed} to the local branch. Once committed,
+the changes (called a @q{commit}) are given a unique 40-digit
+hexadecimal reference number called the @q{Committish} or @q{SHA1
+ID} which identifies the commit to Git. Such committed changes
+can be sent to the master repository by @q{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 @q{diff} or @q{patch}
+(which send just the differences from the master repository).
+
+@subsection Installing git
+
+Obtain Git from
+@uref{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.
+
+@subsection 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 @code{[path]/Git}, but if you intend using
+Git for other projects a directory name like @code{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
+
+@example
+cd [path]/Git
+@end example
+
+to position the shell at your new Git repository.
+
+Note: if [path] contains folders with names containing spaces use
+
+@example
+cd "[path]/Git"
+@end example
+
+Then type
+
+@example
+git init
+@end example
+
+to initialize your Git repository.
+
+Then type (all on one line; the shell will wrap automatically)
+
+@example
+git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
+@end example
+
+to download the lilypond master files.
+
+@warning{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 @q{master} and we shall do that here.
+
+To do this, type
+
+@example
+git checkout -b master origin/master
+@end example
+
+This creates a second branch called @q{master}. You will see two
+warnings (ignore these), and a message advising you that your
+local branch @q{master} has been set up to track the remote
+branch. You now have two branches, a local branch called
+@q{master}, and a tracking branch called @q{origin/master}, which
+is a shortened form of @q{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 @code{exit} or by
+clicking on the usual Windows close-window widget.
+
+@subsection 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
+
+@example
+cd [path]/Git
+git gui
+@end example
+
+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.
+
+@subsection Personalising your local git repository
+
+Open the Git GUI, click on
+
+@example
+Edit -> Options
+@end example
+
+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.
+
+@subsection Checking out a branch
+
+At this stage you have two branches in your local repository,
+both identical. To see them click on
+
+@example
+Branch -> Checkout
+@end example
+
+You should have one local branch called @q{master} and one
+tracking branch called @q{origin/master}. The latter is your
+local copy of the @q{remotes/origin/master} branch in the master
+LilyPond repository. The local @q{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.
+
+@subsection Updating files from @q{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
+
+@example
+Remote -> Fetch from -> origin
+@end example
+
+@noindent
+in the Git GUI.
+
+This will place the latest version of every file, including all
+the changes made by others, into the @q{origin/master} branch of
+the tracking branches in your git repository. You can see these
+files by checking out this branch, but you must @emph{never} edit
+any files while this branch is checked out. Check out your local
+@q{master} branch again.
+
+You then need to merge these fetched files into your local
+@q{master} branch by clicking on
+
+@example
+Merge -> Local Merge
+@end example
+
+@noindent
+and if necessary select the local @q{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 @q{master} branch to
+reflect the current state of the @q{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).
+
+@subsection Editing files
+
+First ensure your @q{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
+@q{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
+
+@example
+Commit -> Amend Last Commit
+@end example
+
+@noindent
+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 @emph{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.
+
+
+@subsection Sending changes to @q{remotes/origin/master}
+
+If you do not have write access to @q{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
+
+@example
+cd [path]/Git
+@end example
+
+if necessary, then produce the patch with
+
+@example
+git format-patch origin
+@end example
+
+This will create a patch file for all the locally committed files
+which differ from @q{origin/master}. The patch file can be found
+in [path]/Git and will have a name formed from the commit message.
+
+@subsection Resolving merge conflicts
+
+As soon as you have committed a changed file your local
+@code{master} branch has diverged from @code{origin/master}, and
+will remain diverged until your changes have been committed in
+@code{remotes/origin/master} and Fetched back into your
+@code{origin/master} branch. Similarly, if a new commit has been
+made to @code{remotes/origin/master} by someone else and Fetched,
+your local @code{master} branch is divergent. You can detect a
+divergent branch by clicking on
+
+@example
+Repository -> Visualise all branch history
+@end example
+
+This opens up a very useful new window called @q{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 @code{master} tag on the same node as the
+@code{remotes/origin/master} tag your branch has diverged from
+@code{origin/master}. This is quite normal if files you have
+modified yourself have not yet been Pushed to
+@code{remotes/origin/master} and Fetched, or if files modified and
+committed by others have been Fetched since you last Merged
+@code{origin/master} into your local @code{master} branch.
+
+If a file being merged from @code{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
+@code{remotes/origin/master} for you has added some changes of his
+own before committing your changes to
+@code{remotes/origin/master}, or if someone else has changed the
+same file since you last fetched the file from
+@code{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]
+
+
+@subsection Other actions
+
+The instructions above describe the simplest way of using git on
+Windows. Other git facilities which may usefully supplement these
+include
+
+@itemize
+@item Using multiple local branches (Create, Rename, Delete)
+@item Resetting branches
+@item Cherry-picking commits
+@item Pushing commits to @w{remote/origin/master}
+@item Using gitk to review history
+@end itemize
+
+Once familiarity with using git on Windows has been gained the
+standard git manuals can be used to learn about these.
+
+
+@node Repository directory structure
+@section Repository directory structure
+
+
+@c TODO: integrate the roadmap better
+@verbatiminclude ROADMAP
+
+
+@node Other Git documentation
+@section Other Git documentation
+
+@itemize
+@item
+Official git man pages:
+@uref{http://www.kernel.org/pub/software/scm/git/docs/}
+
+@item
+More in-depth tutorials: @uref{http://git-scm.com/documentation}
+
+@item
+Book about git: @uref{http://progit.org/,Pro Git}
+@end itemize
+
@cindex Orgelpedalbezeichnung
@cindex Triller
@cindex Offen
+@cindex Halboffen
@cindex Flageolet
@cindex Praller
@cindex Mordent
@lilypond[quote,verbatim]
#(define mydrums '(
- (bassdrum default #f -1)
- (snare default #f 0)
- (hihat cross #f 1)
- (pedalhihat xcircle "stopped" 2)
- (lowtom diamond #f 3)))
-up = \drummode { hh8 hh hh hh hhp4 hhp }
+ (bassdrum default #f -1)
+ (snare default #f 0)
+ (hihat cross #f 1)
+ (halfopenhihat cross "halfopen" 1)
+ (pedalhihat xcircle "stopped" 2)
+ (lowtom diamond #f 3)))
+up = \drummode { hh8 hh hhho hhho hhp4 hhp }
down = \drummode { bd4 sn bd toml8 toml }
\new DrumStaff <<
@cindex marcato
@cindex mordent
@cindex open
+@cindex halfopen
@cindex organ pedal marks
@cindex pedal, indicaciones de
@cindex portato
@lilypond[quote,verbatim]
#(define mydrums '(
- (bassdrum default #f -1)
- (snare default #f 0)
- (hihat cross #f 1)
- (pedalhihat xcircle "stopped" 2)
- (lowtom diamond #f 3)))
-up = \drummode { hh8 hh hh hh hhp4 hhp }
+ (bassdrum default #f -1)
+ (snare default #f 0)
+ (hihat cross #f 1)
+ (halfopenhihat cross "halfopen" 1)
+ (pedalhihat xcircle "stopped" 2)
+ (lowtom diamond #f 3)))
+up = \drummode { hh8 hh hhho hhho hhp4 hhp }
down = \drummode { bd4 sn bd toml8 toml }
\new DrumStaff <<
@lilypond[quote,ragged-right,verbatim]
#(define mydrums '(
- (bassdrum default #f -1)
- (snare default #f 0)
- (hihat cross #f 1)
- (pedalhihat xcircle "stopped" 2)
- (lowtom diamond #f 3)))
-up = \drummode { hh8 hh hh hh hhp4 hhp }
+ (bassdrum default #f -1)
+ (snare default #f 0)
+ (hihat cross #f 1)
+ (halfopenhihat cross "halfopen" 1)
+ (pedalhihat xcircle "stopped" 2)
+ (lowtom diamond #f 3)))
+up = \drummode { hh8 hh hhho hhho hhp4 hhp }
down = \drummode { bd4 sn bd toml8 toml }
\new DrumStaff <<
@item
Minél egyszerűbb a példa, annál gyorsabban tudják mások megérteni és
-segÃteni neked.
+segÃteni neked.
@item
A minimális példán látszik, hogy már te magad is tettel lépéseket a probléma
@item
Ne használj finomhangolásokat (@code{\override}, @code{\set}), hacsaknem
-ezek a hibásak.
+ezek a hibásak.
@end itemize
@divEnd
@warning{Ezek a feladatokhoz szükséges, hogy meglegyen a program és a
dokumentáció forrása, de nem kell hozzájuk teljes fejlesztői környezet.
-Ld. a @rcontrib{Starting with git} c. fejezetet.}
+Ld. a @rcontrib{Starting with Git} c. fejezetet.}
@itemize
@item
@subheading Bonyolult feladatok
@warning{Ezekhez a feladatokhoz szükséges, hogy meglegyen a forráskód,
-és le tudd fordÃtani a LilyPondot. Ld. a @rcontrib{Starting with git} és
+és le tudd fordÃtani a LilyPondot. Ld. a @rcontrib{Starting with Git} és
@rcontrib{Compiling LilyPond} c. fejezeteket.}
Windowst használó felhasználóknak javasoljuk a @emph{lilybuntu} virtuális gép
cÃmen. Ez egy gyakorlatias cikk igen szép LilyPond grafikákkal.
A szerző, Kris Shaffer megjegyzi: @qq{A GNU Lilypond gyönyörű kottaképe után a
kereskedelmi alternatÃvák másodosztályúnak tűnnek.}
-A cikk elérhető @uref{http://www.linuxjournal.com/article/8583, online}.
+A cikk elérhető @uref{http://www.linuxjournal.com/article/8583, online}.
@item
2005. augusztus 20.
A tudás nonprofit megosztása} cÃmű cikkben Ãrnak. A szemléltetÅ‘ példa a
LilyPond. A cikkben szerepelnek egy Jan Nieuwenhuizennel e-mailben készÃtett
riport részletei is. Ez a LilyPond első megjelenése a nyomtatott szakmai
-sajtóban.
+sajtóban.
@item
2005. június
-A LilyPond 2.6-os verziójának kiadásáról megjelenik egy francia cikk a
+A LilyPond 2.6-os verziójának kiadásáról megjelenik egy francia cikk a
@uref{http://linuxfr.org/2005/06/27/19210.html, linuxfr.org} weboldalon.
@item
2004. október
-A @emph{Computer!Totaal} holland informatikai magazin szerkesztői
+A @emph{Computer!Totaal} holland informatikai magazin szerkesztői
@uref{http://lilypond.org/web/images/computer-totaal.jpeg, azt Ãrják a
LilyPondról} a 2004. októberi számban: @qq{A LilyPond egy csodálatos szabad
(nyÃlt forrású) szoftver! [...] A LilyPonddal szedett kotta kivételesen szép.
@emph{Csúcstechnológia a kottaÃrásban: LilyPond} cÃmmel.
@uref{http://www.linuxjournal.com/article.php?sid=7657, 1. rész},
@uref{http://www.linuxjournal.com/article.php?sid=7719, 2. rész}.
-
+
@item
2004. március
Chris Cannam riportot készÃt Han-Wen Nienhuysszal és Jan Nieuwenhuizennel a
linuxmusician.com (ma már nem létező) oldalon. A riport megjelenik a
@uref{http://slashdot.org/article.pl?sid=04/03/13/2054227, slashdot.org}-on
-is.
+is.
@item
2004. február
Gail Selkirk jazzénekes Ãr arról, hogyan
@uref{http://www.songbirdofswing.com/editorial_page/lilypond/,
-Merüljünk bele a LilyPond világába}.
+Merüljünk bele a LilyPond világába}.
@qq{...Könnyedén lejegyezhetsz akár slágereket, akár nagyzenekari műveket, az
eredmény pompás!} (A @uref{http://www.computermusic.co.uk/,
c''\staccato c''\tenuto c''\portato
c''\upbow c''\downbow c''\flageolet
c''\thumb c''^\lheel c''\rheel
- c''^\ltoe c''\rtoe c''\open
+ c''^\ltoe c''\rtoe c''\open c''\halfopen
c''\stopped c''\snappizzicato c''\turn c''\reverseturn
c''\trill c''\prall c''\mordent
c''\prallprall c''\prallmordent c''\upprall
staccato tenuto portato
upbow downbow flageolet
thumb lheel rheel
- ltoe rtoe open
+ ltoe rtoe open halfopen
stopped snappizzicato turn reverseturn
trill prall mordent
prallprall prallmordent upprall
Where the @emph{ContextName} is usually @code{Score},
@code{Staff} or @code{Voice}. It may be omitted,
-in which case @code{Voice} is assumed.
+in which case the current context (typically @code{Voice}) is assumed.
The names of context properties consist of words joined
together with no hyphens or underscores, all except the
# unnumbered sections (except those at top-level!) always go to the same
# file as the previous numbered section
- if (not $docu_name == "web" and not ($element->{number})
+ if (not ($web_manual) and not ($element->{number})
and not ($lastfilename eq '') and ($element->{level} > 1)) {
$filename = $lastfilename;
}
} else {
$lang = "";
}
- my $reldir = "";
- $reldir = "../" if ($Texi2HTML::Config::SPLIT eq 'section');
- my $uplink = $reldir."web/manuals.${lang}html";
+ my $reldir = $ENV{DEPTH};
+ my $uplink = $reldir."/Documentation/web/manuals.${lang}html";
if (not $web_manual) {
print $fh "<p class=\"toc_uplink\"><a href=\"$uplink\"
@tab
Minor triad, major seventh
@tab
-@code{maj7.5-}
+@code{maj7.3-}
@tab
@lilypond[line-width=3\cm,noragged-right, notime]
\chordmode {
- c1:maj7.5-
+ c1:maj7.3-
}
@end lilypond
@cindex organ pedal marks
@cindex turn
@cindex open
+@cindex halfopen
@cindex stopped
@cindex flageolet
@cindex reverseturn
@lilypond[quote,verbatim]
#(define mydrums '(
- (bassdrum default #f -1)
- (snare default #f 0)
- (hihat cross #f 1)
- (pedalhihat xcircle "stopped" 2)
- (lowtom diamond #f 3)))
-up = \drummode { hh8 hh hh hh hhp4 hhp }
+ (bassdrum default #f -1)
+ (snare default #f 0)
+ (hihat cross #f 1)
+ (halfopenhihat cross "halfopen" 1)
+ (pedalhihat xcircle "stopped" 2)
+ (lowtom diamond #f 3)))
+up = \drummode { hh8 hh hhho hhho hhp4 hhp }
down = \drummode { bd4 sn bd toml8 toml }
\new DrumStaff <<
@endpredefined
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{numbers-as-easy-note-heads.ly}
+
+
@seealso
Notation Reference:
@ref{Setting the staff size}.
Inside the chord (within the brackets @code{< >}), before the note to
be altered, place the @code{\\tweak} command, followed by
@code{#'font-size} and define the proper size like @code{#-2} (a tiny
-notehead).
+note head).
--- /dev/null
+%% Do not edit this file; it is automatically
+%% generated from LSR http://lsr.dsi.unimi.it
+%% This file is in the public domain.
+\version "2.13.10"
+
+\header {
+ lsrtags = "tweaks-and-overrides"
+
+ texidoc = "
+When working with grob callbacks, it can be helpful to understand a
+grob's @qq{ancestry}. Most grobs have @qq{parents} which influence the
+positioning of the grob. X- and Y-parents influence the horizontal and
+vertical positions for the grob, respectively. Additionally, each
+parent may have parents of its own.
+
+
+Unfortunately, there are several aspects of a grob's ancestry can lead
+to confusion:
+
+* The types of parents a grob has may depend on context. * For some
+grobs, the X- and Y-parents are the same. * A particular @qq{ancestor}
+may be related to a grob in multiple ways. * The concept of
+@qq{generations} is misleading.
+
+
+For example, the @code{System} grob can be both parent (on the Y-side)
+and grandparent (twice on the X-side) to a @code{VerticalAlignment}
+grob.
+
+
+This macro prints (to the console) a textual representation of a grob's
+ancestry.
+
+
+When called this way
+
+
+@{
+ \\once \\override NoteHead #'before-line-breaking = #display-ancestry
+ c @}
+
+
+The following output is generated:
+
+
+------------------------------------
+
+NoteHead X,Y: NoteColumn
+ X: PaperColumn
+ X,Y: System
+ Y: VerticalAxisGroup
+ X: NonMusicalPaperColumn
+ X,Y: System
+ Y: VerticalAlignment
+ X: NonMusicalPaperColumn
+ X,Y: System
+ Y: System
+
+
+
+"
+ doctitle = "Displaying grob ancestry"
+} % begin verbatim
+
+#(define (grob-name grob)
+ (if (ly:grob? grob)
+ (assoc-ref (ly:grob-property grob 'meta) 'name)
+ #f))
+
+#(define (get-ancestry grob)
+ (if (not (null? (ly:grob-parent grob X)))
+ (list (grob-name grob)
+ (get-ancestry (ly:grob-parent grob X))
+ (get-ancestry (ly:grob-parent grob Y)))
+ (grob-name grob)))
+
+#(define (format-ancestry lst padding)
+ (string-append
+ (symbol->string (car lst))
+ "\n"
+ (let ((X-ancestry
+ (if (list? (cadr lst))
+ (format-ancestry (cadr lst) (+ padding 3))
+ (symbol->string (cadr lst))))
+ (Y-ancestry
+ (if (list? (caddr lst))
+ (format-ancestry (caddr lst) (+ padding 3))
+ (symbol->string (caddr lst)))))
+ (if (equal? X-ancestry Y-ancestry)
+ (string-append
+ (format #f "~&")
+ (make-string padding #\space)
+ "X,Y: "
+ (if (list? (cadr lst))
+ (format-ancestry (cadr lst) (+ padding 5))
+ (symbol->string (cadr lst))))
+ (string-append
+ (format #f "~&")
+ (make-string padding #\space)
+ "X: " X-ancestry
+ "\n"
+ (make-string padding #\space)
+ "Y: " Y-ancestry
+ (format #f "~&"))))
+ (format #f "~&")))
+
+#(define (display-ancestry grob)
+ (display
+ (string-append
+ (format #f "~3&~a~2%" (make-string 36 #\-))
+ (format-ancestry (get-ancestry grob) 0)
+ (format #f "~2&"))))
+
+\relative c' {
+ \once \override NoteHead #'before-line-breaking = #display-ancestry
+ f
+ \once \override Accidental #'before-line-breaking = #display-ancestry
+ \once \override Arpeggio #'before-line-breaking = #display-ancestry
+ <f as c>\arpeggio
+}
+
--- /dev/null
+\version "2.13.11"
+
+\header {
+ lsrtags = "pitches"
+ texidoc = "
+Easy notation note heads use the @code{note-names} property
+of the @code{NoteHead} object to determine what appears inside
+the note head. By overriding this property, it is possible
+to print numbers representing the scale-degree.
+
+A simple engraver can be created to do this for every note head
+object it sees.
+"
+ doctitle = "Numbers as easy note heads"
+}
+
+#(define Ez_numbers_engraver (list
+ (cons 'acknowledgers
+ (list
+ (cons 'note-head-interface
+ (lambda (engraver grob source-engraver)
+ (let* (
+ (context (ly:translator-context engraver))
+ (tonic-pitch (ly:context-property context 'tonic))
+ (tonic-name (ly:pitch-notename tonic-pitch))
+ (grob-pitch (ly:event-property (event-cause grob) 'pitch))
+ (grob-name (ly:pitch-notename grob-pitch))
+ (delta (modulo (- grob-name tonic-name) 7))
+ (note-names (make-vector 7 (number->string (+ 1 delta)))))
+ (ly:grob-set-property! grob 'note-names note-names))))))))
+
+#(set-global-staff-size 26)
+
+\layout {
+ ragged-right = ##t
+ \context {
+ \Voice
+ \consists \Ez_numbers_engraver
+ }
+}
+
+\relative c' {
+ \easyHeadsOn
+ c4 d e f
+ g4 a b c \break
+
+ \key a \major
+ a,4 b cis d
+ e4 fis gis a \break
+
+ \key d \dorian
+ d,4 e f g
+ a4 b c d
+}
--- /dev/null
+% Do not edit this file; it is automatically
+% generated from Documentation/snippets/new
+% This file is in the public domain.
+%% Note: this file works from version 2.13.11
+\version "2.13.11"
+
+\header {
+ lsrtags = "pitches"
+ texidoc = "
+Easy notation note heads use the @code{note-names} property
+of the @code{NoteHead} object to determine what appears inside
+the note head. By overriding this property, it is possible
+to print numbers representing the scale-degree.
+
+A simple engraver can be created to do this for every note head
+object it sees.
+"
+ doctitle = "Numbers as easy note heads"
+} % begin verbatim
+
+
+#(define Ez_numbers_engraver (list
+ (cons 'acknowledgers
+ (list
+ (cons 'note-head-interface
+ (lambda (engraver grob source-engraver)
+ (let* (
+ (context (ly:translator-context engraver))
+ (tonic-pitch (ly:context-property context 'tonic))
+ (tonic-name (ly:pitch-notename tonic-pitch))
+ (grob-pitch (ly:event-property (event-cause grob) 'pitch))
+ (grob-name (ly:pitch-notename grob-pitch))
+ (delta (modulo (- grob-name tonic-name) 7))
+ (note-names (make-vector 7 (number->string (+ 1 delta)))))
+ (ly:grob-set-property! grob 'note-names note-names))))))))
+
+#(set-global-staff-size 26)
+
+\layout {
+ ragged-right = ##t
+ \context {
+ \Voice
+ \consists \Ez_numbers_engraver
+ }
+}
+
+\relative c' {
+ \easyHeadsOn
+ c4 d e f
+ g4 a b c \break
+
+ \key a \major
+ a,4 b cis d
+ e4 fis gis a \break
+
+ \key d \dorian
+ d,4 e f g
+ a4 b c d
+}
generating-random-notes.ly
makam-example.ly
non-traditional-key-signatures.ly
+numbers-as-easy-note-heads.ly
ottava-text.ly
preventing-extra-naturals-from-being-automatically-added.ly
preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly
\version "2.13.10"
\header {
-%% Translation of GIT committish: b7ec64504da87595509ae6e88ae546d6a0ce633d
- texidocfr = "
-Pour obtenir la partition d'un chanson, il suffit d'assembler
-des noms d'accords, une mélodie et des paroles :
-
-"
- doctitlefr = "Chanson simple"
-
lsrtags = "chords"
%% Translation of GIT committish: b2d4318d6c53df8469dfa4da09b27c15a374d0ca
"
doctitlede = "Ein einfaches Liedblatt"
+%% Translation of GIT committish: b7ec64504da87595509ae6e88ae546d6a0ce633d
+ texidocfr = "
+Pour obtenir la partition d'un chanson, il suffit d'assembler
+des noms d'accords, une mélodie et des paroles :
+
+"
+ doctitlefr = "Chanson simple"
texidoc = "
When put together, chord names, a melody, and lyrics form a lead sheet:
customizing-fretboard-fret-diagrams.ly
customizing-markup-fret-diagrams.ly
display-bracket-with-only-one-staff-in-a-system.ly
+displaying-grob-ancestry.ly
dotted-harmonics.ly
drawing-boxes-around-grobs.ly
drawing-circles-around-various-objects.ly
transcription-of-ancient-music-with-incipit.ly
tweaking-clef-properties.ly
tweaking-grace-layout-within-music.ly
+using-ly-grob-object-to-access-grobs-with--tweak.ly
using-postscript-to-generate-special-note-head-shapes.ly
using-the--tweak-command-to-tweak-individual-grobs.ly
vertically-aligned-dynamics-and-textscripts.ly
--- /dev/null
+%% Do not edit this file; it is automatically
+%% generated from LSR http://lsr.dsi.unimi.it
+%% This file is in the public domain.
+\version "2.13.10"
+
+\header {
+ lsrtags = "tweaks-and-overrides"
+
+ texidoc = "
+Some grobs can be accessed @qq{laterally} from within another grob's
+callback. These are usually listed as @qq{layout objects} in the
+@qq{Internal properties} section of a grob-interface. The function
+@code{ly:grob-object} is used to access these grobs.
+
+
+Demonstrated below are some ways of accessing grobs from within a
+NoteHead callback, but the technique is not limited to NoteHeads.
+However, the NoteHead callback is particularly important, since it is
+the implicit callback used by the @code{\\tweak} command.
+
+
+The example function defined below (\"display-grobs\") is probably not
+that useful, but it demonstrates that the grobs are indeed being
+accessed.
+
+
+Example console output:
+
+
+-------------------- #-Grob Accidental - #-Grob Arpeggio - #-Grob Stem -
+
+
+
+"
+ doctitle = "Using ly:grob-object to access grobs with \\tweak"
+} % begin verbatim
+
+#(define (notehead-get-accidental notehead)
+ ;; notehead is grob
+ (ly:grob-object notehead 'accidental-grob))
+
+#(define (notehead-get-arpeggio notehead)
+ ;; notehead is grob
+ (let ((notecolumn (notehead-get-notecolumn notehead)))
+ (ly:grob-object notecolumn 'arpeggio)))
+
+#(define (notehead-get-notecolumn notehead)
+ ;; notehead is grob
+ (ly:grob-parent notehead X))
+
+#(define (notehead-get-stem notehead)
+ ;; notehead is grob
+ (let ((notecolumn (notehead-get-notecolumn notehead)))
+ (ly:grob-object notecolumn 'stem)))
+
+#(define (display-grobs notehead)
+ ;; notehead is grob
+ (let ((accidental (notehead-get-accidental notehead))
+ (arpeggio (notehead-get-arpeggio notehead))
+ (stem (notehead-get-stem notehead)))
+ (format #t "~2&~a\n" (make-string 20 #\-))
+ (for-each
+ (lambda (x) (format #t "~a\n" x))
+ (list accidental arpeggio stem))))
+
+\relative c' {
+ %% display grobs for each note head:
+ %\override NoteHead #'before-line-breaking = #display-grobs
+ <c
+ %% or just for one:
+ \tweak #'before-line-breaking #display-grobs
+ es
+ g>1\arpeggio
+}
+
@set FDL
@set web
@include macros.itexi
+@include weblinks.itexi
@afourpaper
@warning{These jobs generally require that you have the program
and documentation source files, but do not require a full
-development environment. See @rcontrib{Starting with git}.}
+development environment. See @rcontrib{Starting with Git}.}
@itemize
@item
@subheading Complex tasks
@warning{These jobs generally require that you have the source
-code and can compile LilyPond. See @rcontrib{Starting with git},
+code and can compile LilyPond. See @rcontrib{Starting with Git},
and @rcontrib{Compiling LilyPond}.}
We suggest that new contributors using Windows use a virtual
@divEnd
-@divClass{column-right-top}
+@divClass{column-center-top}
@subheading Regression tests
@divClass{keep-bullets}
@itemize
-@item @uref{../../input/regression/collated-files.html, Regression tests}:
-This release's tests. (also in
-@uref{../input/regression/collated-files.pdf, pdf})
+@ifclear web_version
+
+@item
+@uref{../../input/regression/collated-files.html, Regression tests}:
+This releases' regtests.
+(@uref{../../input/regression/collated-files.pdf, pdf version})
+
+@item
+@uref{../../input/regression/musicxml/collated-files.html, MusicXML tests}:
+This releases' musicXML tests.
+(@uref{../../input/regression/musicxml/collated-files.pdf, pdf version})
+@end ifclear
+
+@ifset web_version
+@item @regtestDevel (@regtestDevelPdf{})
+
+@item @regtestDevelXml (@regtestDevelXmlPdf{})
+
+@item @regtestStable (@regtestStablePdf{})
+
+@item @regtestStableXml (@regtestStableXmlPdf{})
+@end ifset
-@item @uref{../../input/regression/musicxml/collated-files.html,
-MusicXML Regression tests}:
-This release's MusicXML tests. (also in
-@uref{../input/regression/musicxml/collated-files.pdf, pdf})
@item @uref{http://lilypond.org/test, Archive of regression tests}:
Comparisons between versions.
@divClass{column-center-bottom}
@subheading Manuals
+@ifclear web_version
+@warning{These manuals are for LilyPond @version{}; the latest
+manuals can be found at @url{http://lilypond.org}}
+@end ifclear
+
@divClass{normal-table}
@multitable @columnfractions .3 .3 .3
@headitem Introduction
@docLinkPdf{Extending,extending,@manualDevelExtendingPdf}
@item
-@docLinkSplit{Internals,Internals,@manualDevelInternalsSplit}
+@docLinkSplit{Internals,internals,@manualDevelInternalsSplit}
@tab
-@docLinkBig{Internals,Internals,@manualDevelInternalsBig}
+@docLinkBig{Internals,internals,@manualDevelInternalsBig}
@tab
-@docLinkPdf{Internals,Internals,@manualDevelInternalsPdf}
+@docLinkPdf{Internals,internals,@manualDevelInternalsPdf}
+
+@ifset web_version
+@headitem Downloadable
+
+@item
+@doctarballDevel
+@end ifset
@end multitable
@c for @version won't be up yet!
@heading Downloads for LilyPond @versionDevel
-Links for the stable version of LilyPond can be found on
-@uref{http://lilypond.org, lilypond.org}
+@warning{Links for the stable version of LilyPond can be found at
+@uref{http://lilypond.org, lilypond.org}}
@end ifclear
@ifset web_version
@heading Downloads for LilyPond @versionStable
@downloadStableSource{}
For an extensive listing of all versions (old and new), see our
-@uref{http://download.linuxaudio.org/lilypond/binaries/, download
-site}.
+@uref{http://download.linuxaudio.org/lilypond/source/?C=N;O=D,
+download site}.
@divEnd
-\version "2.13.6"
+\version "2.13.11"
#(set-global-staff-size 22.45)
(- (ly:pitch-alteration right-pitch) (ly:pitch-alteration left-pitch))
0 )))
-%% Hide fret number: useful to draw slide into/from a casual point of
-%% the fretboard.
-hideFretNumber = { \once \override TabNoteHead #'transparent = ##t
- \once \override NoteHead #'transparent = ##t
- \once \override Stem #'transparent = ##t
- \once \override NoteHead #'no-ledgers = ##t
+% Hide fret number: useful to draw slide into/from a casual point of
+% the fretboard.
+hideFretNumber = {
+ \once \override TabNoteHead #'transparent = ##t
+ \once \override TabNoteHead #'whiteout = ##f
+ \once \override NoteHead #'transparent = ##t
+ \once \override Stem #'transparent = ##t
+ \once \override NoteHead #'no-ledgers = ##t
}
\paper {
line-width= #180
}
-upper= \relative c' {
+upper= \relative c' {
\time 4/4
\key e \major
\set Staff.midiInstrument = #"acoustic guitar (steel)"
\set fingeringOrientations = #'(left)
- %\override Staff.Glissando #'extra-offset = #' (0.0 . 1.0)
- \partial 4. \acciaccatura c16 \glissando cis8 e4
- < cis-1 g'-3 >2 s8 \grace a16 ( \glissando <b-2>8\3 ) <d-1> ( b ) |
- <e-3>\2 ( <d-1> b ) \grace <ais-2>16 ( \glissando a8 g ) s4. |
- s4. < d'\3 g\2 >8 < gis,\4 d'\3 fis\2 >2\arpeggio ~ |
-
- < gis\4 d'\3 fis\2 >2 < b'\2\harmonic e\harmonic >2\fermata |
-
+ \partial 4. \acciaccatura c16 \glissando cis8 e4
+ < cis-1 g'-3 >2 s8 \grace a16 ( \glissando < b-2 >8\3 ) < d-1 > ( b )
+ < e-3 >\2 ( <d-1> b ) \grace < ais-2 >16 ( \glissando a8 g ) s4.
+ s4. < d'\3 g\2 >8 < gis,\4 d'\3 fis\2 >2\arpeggio ~
+ < gis\4 d'\3 fis\2 >2 < b'\2\harmonic e\harmonic >2\fermata
}
-lower= \relative c {
+lower= \relative c {
\set fingeringOrientations = #'(left)
- \partial 4. s4. |
- s4 e,4 s2 |
- s2 s8 <e'-3>4. ~ |
- e4 \hideFretNumber \grace { b8 \glissando s4 } <e-2>4\5 e,2 ~ |
-
- e2 < e'\6\harmonic > |
+ \partial 4. s4.
+ s4 e,4 s2
+ s2 s8 < e'-3 >4. ~
+ e4 \hideFretNumber \grace { b8 \glissando s4 } < e-2 >4\5 e,2 ~
+ e2 < e'\6\harmonic >
}
\score {
\new StaffGroup <<
\new Staff = "guitar" <<
- \context Voice = "upper guitar" { \clef "G_8" \voiceOne
- \override Glissando #'gap = #0.5
- \override Glissando #'extra-offset = #'(-0.5 . 0)
- \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
- \override Glissando #'minimum-length = #4
- \override Glissando #'extra-dy = #glissando::calc-extra-dy
- \upper }
- \context Voice = "lower guitar" { \clef "G_8" \voiceTwo
- \override Glissando #'bound-details #'right #'padding = #1
- \override Glissando #'bound-details #'left #'padding = #0.2
- \lower }
+ \context Voice = "upper guitar" {
+ \clef "G_8" \voiceOne
+ \override Glissando #'gap = #0.5
+ \override Glissando #'extra-offset = #'(-0.5 . 0)
+ \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
+ \override Glissando #'minimum-length = #4
+ \override Glissando #'extra-dy = #glissando::calc-extra-dy
+ \upper
+ }
+ \context Voice = "lower guitar" {
+ \clef "G_8" \voiceTwo
+ \override Glissando #'bound-details #'right #'padding = #1
+ \override Glissando #'bound-details #'left #'padding = #0.2
+ \lower
+ }
>>
\new TabStaff = "tab" <<
\context TabVoice = "upper tab" { \clef "moderntab" \voiceOne \upper }
\context TabVoice = "lower tab" { \clef "moderntab" \voiceTwo \lower }
>>
>>
- %{
- \midi {
- \context {
- \Score tempoWholesPerMinute = #(ly:make-moment 120 4)
- }
- }
- %}
- \layout {
+ \layout {
\context {
- \Staff
- \override StringNumber #'transparent = ##t
+ \Staff
+ \override StringNumber #'transparent = ##t
}
-
\context {
- \TabStaff
- \revert Arpeggio #'stencil
+ \TabStaff
+ \revert Arpeggio #'stencil
}
}
-}
\ No newline at end of file
+}
@divClass{column-left-top}
@subheading Downloadable versions
-@help{compare tarball vs. zip size, ask about windows users
-dealing with tarballs (both gz and bz2), etc.}
-
-@help{on second thought, wait until the new doc build. write an
-apology here for no tarballs}
+@ifclear web_version
+Downloadable tarballs only available at @uref{http://lilypond.org}
+@end ifclear
+@ifset web_version
@divClass{keep-bullets}
@itemize
-@item html-split zip
-
-@item html-big zip
-
-@item pdf zip
-
-@item info zip maybe?!?!
+@item @doctarballStable
@end itemize
@divEnd
+@end ifset
+
@divEnd
@divClass{column-right-bottom}
@c FIXME: fill in number
@c used for news about the upcoming release; see CG x.y
@c DO NOT WRITE BETWEEN THESE LINES
+@newsItem
+@subsubheading LilyPond 2.13.11 released! @emph{January 16, 2010}
+
+We are happy to announce the release of LilyPond 2.13.11. This
+release is intended for developers only, and brings a number of
+improvements to the build system, Contributor's Guide, and fixes 4
+critical regressions against earlier versions.
+
+@newsEnd
+@c DO NOT WRITE BETWEEN THESE LINES
+
+
@newsItem
@subsubheading LilyPond 2.13.10 released! @emph{December 31, 2009}
and English names for feta filenames.
@newsEnd
-@c DO NOT WRITE BETWEEN THESE LINES
@newsItem
@newsEnd
-@newsItem
-@subsubheading LilyPond 2.13.9 released! @emph{December 12, 2009}
-
-LilyPond 2.13.9 is now out. From 2.13.9 onwards, LilyPond is
-licensed under the GNU GPL v3+ for code, and the GNU FDL 1.3+ for
-documentation. In addition to the usual round of bugfixes, this
-release adds a shortcut for repeated chords.
-
-Please note that 2.13 is an @strong{unstable development} branch;
-normal users should continue to use 2.12.
-
-@newsEnd
-
@end ignore
+@newsItem
+@subsubheading LilyPond 2.13.9 released! @emph{December 12, 2009}
+
+LilyPond 2.13.9 is now out. From 2.13.9 onwards, LilyPond is
+licensed under the GNU GPL v3+ for code, and the GNU FDL 1.3+ for
+documentation. In addition to the usual round of bugfixes, this
+release adds a shortcut for repeated chords.
+
+Please note that 2.13 is an @strong{unstable development} branch;
+normal users should continue to use 2.12.
+
+@newsEnd
+
@newsItem
@subsubheading New Website! @emph{October 3, 2009}
Prebuilt Documentation and packages are available from:
- http://lilypond.org
+ http://www.lilypond.org
LilyPond development is hosted at:
http://savannah.gnu.org/projects/lilypond
-Here is a simple explanation of the directory layout for LilyPond's
-source files.
+Here is a simple explanation of the directory layout for
+LilyPond's source files.
- . Toplevel READMEs, ChangeLog, build bootstrapping,
- patches for third party programs
- Documentation/
- application/ Source files for Application Usage manual
- essay/ Academic material and .bib files with references
- to books and articles
- contributor/ Source files for the Contributor's Guide
- css/ CSS files for documentation in HTML
- extending/ Source files for the Extending manual
- included/ Snippets included in manuals
- learning/ Source files for the Learning Manual
- logo/ The logo
- misc/ Old announcements, ChangeLogs and NEWS
- notation/ Source files for Notation Reference manual
- pictures/ Pictures and graphics used in the documentation
- snippets/ Snippets from the LilyPond Snippet Repository
- (auto-generated, do not modify!)
- new/ Snippets which are too new for LSR
- topdocs/ Sources for the toplevel READMEs
- (README.txt, INSTALL.txt etc.)
- po/ Translations for build and maintenance scripts
- web/ lilypond.org website (a.k.a. General Information for
- offline documentation)
- ly-examples/ LilyPond examples for the website
- fr/ es/ de/ Docs translated to French, Spanish, German, resp.
- ja/ hu/ it/ Docs translated to Japanese, Hungarian, Italian, resp.
- Every subdirectory of Documentation/ that contains localizable
- source files may be present in the directory of a translation;
- in addition, each translation directory may contain a ubsdirectory
- texidocs/ that contains the translation of snippets texidocs.
- elisp/ Emacs LilyPond mode and syntax coloring
- flower/ A simple C++ library
- input/ Music input examples
- regression/ Testing of features, one test per file
- lily/ C++ sources for the LilyPond binary
- ly/ System music include files
- make/ Specific make subroutines
- mf/ MetaFont sources for the Emmentaler and Aybabtu fonts
- po/ Translations for binaries and end-user scripts
- ps/ PostScript library files
- python/ Python modules, MIDI module
- auxiliar/ Python modules used by maintenance scripts
- or in the build process
- scm/ Scheme sources for LilyPond and subroutine files
- scripts/ End-user scripts
- auxiliar/ Scripts for maintaining the sources and scripts
- for the build process that need not be built
- build/ Scripts for the build process that must be built
- stepmake/ Generic make subroutine files
- tex/ TeX and texinfo library files
- vim/ Vi(M) LilyPond mode and syntax coloring
+
+. Toplevel READMEs, ChangeLog,
+| build bootstrapping, patches
+| for third party programs
+|
+|-- Documentation/ Top sources for manuals
+| |
+| |
+| | INDIVIDUAL CHAPTERS FOR EACH MANUAL:
+| |
+| |-- contributor/ Contributor's Guide
+| |-- essay/ Essay on automated music engraving
+| |-- extending/ Extending
+| |-- learning/ Learning Manual
+| |-- notation/ Notation Reference
+| |-- usage/ Usage
+| |-- web/ The website
+| | `-- ly-examples/ .ly files for the "Examples" page
+| |
+| |
+| | TRANSLATED MANUALS:
+| |
+| |-- de/ German
+| |-- es/ Spanish
+| |-- fr/ French
+| |-- hu/ Hungarian
+| |-- it/ Italian
+| |-- ja/ Japanese
+| |-- nl/ Dutch
+| |
+| |
+| | MISCELLANEOUS DOC STUFF:
+| |
+| |-- css/ CSS files for HTML docs
+| |-- included/ .ly files used in the manuals
+| |-- logo/ Web logo and "note" icon
+| |-- misc/ Old announcements, ChangeLogs and NEWS
+| |-- pictures/ Images used (eps/jpg/png/svg)
+| | `-- pdf/ (pdf)
+| |-- po/ Translated build/maintenance scripts
+| |-- snippets/ Auto-generated .ly snippets (from the LSR)
+| | `-- new/ Snippets too new for the LSR
+| `-- topdocs/ AUTHORS, INSTALL, README
+|
+|
+| C++ SOURCES:
+|
+|-- flower/ A simple C++ library
+|-- lily/ C++ sources for the LilyPond binary
+|
+|
+| LIBRARIES:
+|
+|-- ly/ .ly \include files
+|-- mf/ MetaFont sources for Emmentaler and Aybabtu fonts
+|-- ps/ PostScript library files
+|-- scm/ Scheme sources for LilyPond and subroutine files
+|-- tex/ TeX and texinfo library files
+|
+|
+| SCRIPTS:
+|
+|-- python/ Python modules, MIDI module
+| `-- auxiliar/ Python modules for build/maintenance
+|-- scripts/ End-user scripts (--> lilypond/usr/bin/)
+| |-- auxiliar/ Maintenance and non-essential build scripts
+| `-- build/ Essential build scripts
+|
+|
+| BUILD PROCESS:
+| (also see SCRIPTS section above)
+|
+|-- make/ Specific make subroutine files
+|-- stepmake/ Generic make subroutine files
+|
+|
+| REGRESSION TESTS:
+|
+|-- input/
+| `-- regression/ .ly regression tests
+| |-- abc2ly/ .abc regression tests
+| `-- musicxml/ .xml and .itexi regression tests
+|
+|
+| MISCELLANEOUS:
+|
+|-- elisp/ Emacs LilyPond mode and syntax coloring
+|-- vim/ Vi(M) LilyPond mode and syntax coloring
+`-- po/ Translations for binaries and end-user scripts
PACKAGE_NAME=LilyPond
MAJOR_VERSION=2
MINOR_VERSION=13
-PATCH_LEVEL=11
+PATCH_LEVEL=12
MY_PATCH_LEVEL=
VERSION_STABLE=2.12.3
-VERSION_DEVEL=2.13.10
+VERSION_DEVEL=2.13.11
--- /dev/null
+\version "2.13.11"
+\header {
+ texidoc = "The left text of a @code{DynamicTextSpanner} is
+left-aligned to its anchor note.
+"
+}
+
+\relative c' {
+ \crescTextCresc
+ \dimTextDim
+ c4\< c c c\!
+ c4\> c c c\!
+}
--- /dev/null
+\version "2.13.11"
+\header {
+ texidoc = "The space between an absolute dynamic and a dynamic text
+span can be changed using @code{'right-padding}.
+"
+}
+
+\relative c' {
+ \dimTextDim
+ \once \override DynamicText #'right-padding = #0
+ c4\fff\> c c c\!
+}
--- /dev/null
+\version "2.13.11"
+
+\header {
+ texidoc = "A sublist of grob property lists may be overridden within a callback.
+ This test uses a custom stencil callback which changes the Y coordinate
+ of the right bound of the glissando spanner."
+}
+
+\relative c' {
+ \override Glissando #'after-line-breaking =
+ #(lambda (grob)
+ (ly:grob-set-nested-property! grob '(bound-details right Y) 3))
+ c1 \glissando
+ d1
+}
+
return SCM_UNSPECIFIED;
}
+LY_DEFINE (ly_grob_set_nested_property_x, "ly:grob-set-nested-property!",
+ 3, 0, 0, (SCM grob, SCM symlist, SCM val),
+ "Set nested property @var{symlist} in grob @var{grob} to value @var{val}.")
+{
+ Grob *sc = unsmob_grob (grob);
+
+ LY_ASSERT_SMOB (Grob, grob, 1);
+
+ bool type_ok = ly_cheap_is_list (symlist);
+
+ if (type_ok)
+ for (SCM s = symlist; scm_is_pair (s) && type_ok; s = scm_cdr (s))
+ type_ok &= ly_is_symbol (scm_car (s));
+
+ SCM_ASSERT_TYPE (type_ok, symlist, SCM_ARG2, __FUNCTION__, "list of symbols");
+
+ set_nested_property (sc, symlist, val);
+ return SCM_UNSPECIFIED;
+}
+
+
LY_DEFINE (ly_grob_property, "ly:grob-property",
2, 1, 0, (SCM grob, SCM sym, SCM val),
"Return the value for property @var{sym} of @var{grob}."
if (finished_spanner_)
finished_spanner_->set_bound (RIGHT, script_);
if (current_spanner_)
- {
- current_spanner_->set_bound (LEFT, script_);
-
- if (!Hairpin::has_interface (current_spanner_))
- set_nested_property (current_spanner_,
- scm_list_3 (ly_symbol2scm ("bound-details"),
- ly_symbol2scm ("left"),
- ly_symbol2scm ("attach-dir")),
- scm_from_int (RIGHT));
- }
+ current_spanner_->set_bound (LEFT, script_);
}
}
%ragged-right = ##t
ragged-last = ##t
- %%% FIXME: line-thickness should be set here to a slightly
- %%% thicker value as the default; but we can not set it here,
- %%% since neither \staff-space nor #staff-space is yet defined
- %%% when lily comes across the following line.
- %line-thickness = \staff-space / 7.0
+ line-thickness = #(/ (ly:output-def-lookup $defaultpaper 'staff-space) 7.0)
\context {
\VaticanaStaff
espressivo = #(make-articulation "espressivo")
fermata = #(make-articulation "fermata")
flageolet = #(make-articulation "flageolet")
+halfopen = #(make-articulation "halfopen")
lheel = #(make-articulation "lheel")
lineprall = #(make-articulation "lineprall")
longfermata = #(make-articulation "longfermata")
$(top-build-dir)/Documentation/$(outdir)/%-big-page.$(ISOLANG).html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.$(ISOLANG).xref-map $(TRANSLATION_LILY_IMAGES)
$(TEXI2HTML) -D bigpage $(TEXI2HTML_FLAGS) --output=$@ $<
-$(top-build-dir)/Documentation/$(outdir)/%.$(ISOLANG).html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.$(ISOLANG).xref-map $(outdir)/version.itexi
+$(top-build-dir)/Documentation/$(outdir)/%.$(ISOLANG).html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.$(ISOLANG).xref-map $(outdir)/version.itexi $(outdir)/weblinks.itexi
$(TEXI2HTML) $(TEXI2HTML_FLAGS) --output=$@ $<
$(top-build-dir)/Documentation/$(outdir)/%.$(ISOLANG).pdf: $(outdir)/%.texi
$(outdir)/version.%: $(top-src-dir)/VERSION
$(PYTHON) $(top-src-dir)/scripts/build/create-version-itexi.py > $@
+$(outdir)/weblinks.%: $(top-src-dir)/VERSION
+ $(PYTHON) $(top-src-dir)/scripts/build/create-weblinks-itexi.py > $@
+
$(outdir)/%.png: $(top-build-dir)/Documentation/$(outdir)/%.png
ln -f $< $@
find $(outdir) \( -name 'lily-*.png' -o -name 'lily-*.ly' \) | sed 's!$(outdir)/!!g' | xargs $(buildscript-dir)/mass-link hard $(outdir) $(top-build-dir)/Documentation/$(outdir)
touch $@
-$(outdir)/lilypond-%.info: $(outdir)/%.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi
+$(outdir)/lilypond-%.info: $(outdir)/%.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi $(outdir)/weblinks.itexi
$(MAKEINFO) -I$(src-dir) -I$(outdir) --output=$@ $<
$(outdir)/index.$(ISOLANG).html: TEXI2HTML_INIT = $(WEB_TEXI2HTML_INIT)
TEXI2HTML_INCLUDES += --I=. --I=$(src-dir) --I=$(outdir) $(DOCUMENTATION_INCLUDES) --I=$(XREF_MAPS_DIR)
TEXI2HTML_FLAGS += $(TEXI2HTML_INCLUDES) $(TEXI2HTML_LANG) $(TEXI2HTML_INIT)
-TEXI2HTML = TOP_SRC_DIR=$(top-src-dir) PERL_UNICODE=SD $(TEXI2HTML_PROGRAM)
+TEXI2HTML = TOP_SRC_DIR=$(top-src-dir) DEPTH=$(depth) PERL_UNICODE=SD $(TEXI2HTML_PROGRAM)
###########
TEXI2PDF_FLAGS += --batch $(DOCUMENTATION_INCLUDES)
fet_endchar;
+fet_beginchar ("halfopen (unstopped)", "halfopen");
+ save thin, height, width, thick, factor, slash;
+
+ factor = 5/4;
+ height# = 5/4 width#;
+ height# = staff_space#;
+ thin = 0.6 linethickness + 0.06 staff_space;
+ slash# = 1.05 linethickness#;
+
+ set_char_box (width# / 2, width# / 2, height# / 2, height# / 2);
+
+ define_pixels (width, height, slash);
+
+ 2 thick + 0.6 (height - 2 thin) = width;
+
+ penpos1 (thick, 0);
+ penpos2 (thin, 90);
+ penpos3 (thick, 180);
+ penpos4 (thin, 270);
+ z1r = (w, 0);
+ z2r = (0, h);
+ z3r = (-w, 0);
+ z4r = (0, -h);
+
+ penlabels (1, 2, 3, 4);
+
+ penstroke z1e{up}
+ .. z2e{left}
+ .. z3e{down}
+ .. z4e{right}
+ .. cycle;
+
+ draw_brush ((-w * factor, -h * factor), slash,
+ (w * factor, h * factor), slash);
+fet_endchar;
+
+
fet_beginchar ("plus (stopped)", "stopped");
save hthick, vthick, size, outer_hsize, outer_vsize;
"Dynamic line spanner."
'(avoid-slur))
+(ly:add-interface
+ 'dynamic-text-interface
+ "An absolute text dynamic."
+ '(right-padding))
+
(ly:add-interface
'dynamic-text-spanner-interface
"Dynamic text spanner."
(font-shape . italic)
(outside-staff-priority . 250)
(positioning-done . ,ly:script-interface::calc-positioning-done)
+ (right-padding . 0.5)
(self-alignment-X . ,CENTER)
(self-alignment-Y . ,CENTER)
(stencil . ,ly:text-interface::print)
(Y-offset . ,ly:self-alignment-interface::y-aligned-on-self)
(meta . ((class . Item)
(interfaces . (dynamic-interface
+ dynamic-text-interface
font-interface
script-interface
self-alignment-interface
(DynamicTextSpanner
. (
+ (before-line-breaking . ,dynamic-text-spanner::before-line-breaking)
(bound-details . ((right . ((attach-dir . ,LEFT)
(Y . 0)
(padding . 0.75)
(left . ((attach-dir . ,LEFT)
(Y . 0)
- (stencil-offset . (0 . -0.5))
- (padding . 0.5)
+ (stencil-offset . (-0.75 . -0.5))
+ (padding . 0.75)
))
(left-broken . ((attach-dir . ,RIGHT)
))
}
@end lilypond"
(if (> amount 0)
- (ly:make-stencil "" (cons 0 amount) '(-1 . 1))
- (ly:make-stencil "" (cons amount amount) '(-1 . 1))))
+ (ly:make-stencil "" (cons 0 amount) '(0 . 0))
+ (ly:make-stencil "" (cons amount amount) '(0 . 0))))
;; todo: fix negative space
(define-markup-command (vspace layout props amount)
START
STOP))
+(define-public (dynamic-text-spanner::before-line-breaking grob)
+ "Monitor left bound of @code{DynamicTextSpanner} for absolute dynamics.
+If found, ensure @code{DynamicText} does not collide with spanner text by
+changing @code{'attach-dir} and @code{'padding}. Reads the
+@code{'right-padding} property of @code{DynamicText} to fine tune space
+between the two text elements."
+ (let ((left-bound (ly:spanner-bound grob LEFT)))
+ (if (grob::has-interface left-bound 'dynamic-text-interface)
+ (let* ((details (ly:grob-property grob 'bound-details))
+ (left-details (ly:assoc-get 'left details))
+ (my-padding (ly:assoc-get 'padding left-details))
+ (script-padding (ly:grob-property left-bound 'right-padding 0)))
+
+ (and (number? my-padding)
+ (ly:grob-set-nested-property! grob
+ '(bound-details left attach-dir)
+ RIGHT)
+ (ly:grob-set-nested-property! grob
+ '(bound-details left padding)
+ (+ my-padding script-padding)))))))
+
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; lyrics
(direction . ,UP)))
+ ("halfopen"
+ . (
+ (avoid-slur . outside)
+ (padding . 0.20)
+ (script-stencil . (feta . ("halfopen" . "halfopen")))
+ (direction . ,UP)))
+
+
("ictus"
. (
(script-stencil . (feta . ("ictus" . "ictus")))
# set to 1 to set up for translation, to 0 for other
set translator 0
+# location of lilypond git
+set lily_dir $env(HOME)/lilypond-git
+
+
if {$translator == 1} {
set windowTitle \
"LilyPond Translator's Git Interface version $version"
# Helper functions
-set lily_dir $env(HOME)/lilypond-git
if {[file exists $lily_dir]} {
cd $lily_dir
}
print "@end macro"
print ""
-def make_download(name, osA, osB, version, revision, text):
- string = "@uref{http://download.linuxaudio.org/lilypond/binaries/"
- string += osA + "lilypond-"
- string += version + "-" + revision
- string += "." + osB + ",\n"
- string += text
- string += ": LilyPond "
- string += version + "-" + revision
- string += "}"
- make_macro(name, string)
-
-def make_download_source(name, vstring, version):
- string = "@uref{http://download.linuxaudio.org/lilypond/sources/"
- string += vstring + "/"
- string += "lilypond-" + version + ".tar.gz"
- string += ", "
- string += "Source: lilypond-" + version + ".tar.gz"
- string += "}"
- make_macro(name, string)
-
-def make_all_downloads(macroName, version):
- make_download("download"+macroName+"LinuxNormal", "linux-x86/",
- "linux-x86.sh", version, "1", "Linux x86")
- make_download("download"+macroName+"LinuxBig", "linux-64/",
- "linux-64.sh", version, "1", "Linux 64")
- make_download("download"+macroName+"LinuxPPC", "linux-ppc/",
- "linux-ppc.sh", version, "1", "Linux PPC")
-
- make_download("download"+macroName+"FreeBSDNormal", "freebsd-x86/",
- "freebsd-x86.sh", version, "1", "FreeBSD i386")
- make_download("download"+macroName+"FreeBSDBig", "freebsd-x86/",
- "freebsd-64.sh", version, "1", "FreeBSD amd64")
-
- make_download("download"+macroName+"DarwinNormal", "darwin-x86/",
- "darwin-x86.tar.bz2", version, "1", "MacOS X x86")
- make_download("download"+macroName+"DarwinPPC", "darwin-ppc/",
- "darwin-ppc.tar.bz2", version, "1", "MacOS X PPC")
-
- make_download("download"+macroName+"Windows", "mingw/",
- "mingw.exe", version, "1", "Windows")
-
-def make_ver_link(macroname, version, url, linktext):
- string = "@uref{"
- string += url
- string += ","
- string += linktext
- string += "}"
- make_macro(macroname, string)
-
-# TODO: this kind of thing should really be in a central place for
-# lilypond python build scripts
-def translateNameToUrl(manual, version):
- ver_split = version.split('.')
- ver_minor = ver_split[0] + '.' + ver_split[1]
- url = depth + "doc/v" + ver_minor + "/Documentation/"
-
- if (ver_minor == '2.13'):
- return url+manual
- if (ver_minor == '2.12'):
- if (manual=='learning'):
- return url+'user/lilypond-learning'
- elif (manual=='internals'):
- return url+'user/lilypond-internals'
- elif (manual=='notation'):
- return url+'user/lilypond'
- elif (manual=='usage'):
- return url+'user/lilypond-program'
- elif (manual=='snippets'):
- return url+'../input/lsr/lilypond-snippets'
- elif (manual=='changes'):
- return url+'topdocs/NEWS.html'
- elif (manual=='music-glossary'):
- return url+'user/music-glossary'
- elif (manual=='essay'):
- return url+'user/lilypond-learning/Background.html'
- elif (manual=='extending'):
- return url+'user/lilypond/Interfaces-for-programmers.html'
- else:
- return ''
-
-
-def make_manual_links(name, version):
- for m in manuals:
- manual = m
- if (m=='music-glossary'):
- mshort = 'Glossary'
- else:
- mshort = m.capitalize()
- url = translateNameToUrl(m, version)
-
- if (url == ''):
- # can't have a comma here due to texinfo
- make_ver_link("manual"+name+mshort+'Pdf',
- version, "http://lilypond.org",
- mshort+" (did not exist in 2.12)")
- make_ver_link("manual"+name+mshort+'Split',
- version, "http://lilypond.org",
- mshort+" (did not exist in 2.12)")
- make_ver_link("manual"+name+mshort+'Big',
- version, "http://lilypond.org",
- mshort+" (did not exist in 2.12)")
- make_ver_link("manual"+name+mshort+'SplitNoName',
- version, "http://lilypond.org",
- mshort+" (did not exist in 2.12)")
- continue
- make_ver_link("manual"+name+mshort+'Pdf',
- version,
- url + '.pdf',
- manual.capitalize() + '.pdf')
- make_ver_link("manual"+name+mshort+'Split',
- version,
- url + '/index.html',
- manual.capitalize() + ' (split HTML)')
- make_ver_link("manual"+name+mshort+'Big',
- version,
- url + '-big-page.html',
- manual.capitalize() + ' (big HTML)')
- # this is stupid and I shouldn't have bothered trying
- # to support the 2.12 docs and it will be deleted once
- # 2.14 is out and the website won't be visible to users
- # until 2.14 is out. -gp
- if (url.endswith('.html')):
- newurl = url
- else:
- newurl = url + '/index.html'
- make_ver_link("manual"+name+mshort+'SplitNoName',
- version,
- newurl,
- manual.capitalize())
-
-
print "@c ************************ Version numbers ************"
make_macro("version", VERSION)
make_macro("versionStable", VERSION_STABLE)
make_macro("versionDevel", VERSION_DEVEL)
-print "@c ************************ Download binaries ************"
-make_all_downloads("Stable", VERSION_STABLE)
-make_all_downloads("Devel", VERSION_DEVEL)
-
-print "@c ************************ Download source ************"
-# FIXME: icky hard-coding! -gp
-make_download_source("downloadStableSource", "v2.12", VERSION_STABLE)
-make_download_source("downloadDevelSource", "v2.13", VERSION_DEVEL)
-
-print "@c ************************ Manual links ************"
-make_manual_links("Stable", VERSION_STABLE)
-make_manual_links("Devel", VERSION_DEVEL)
-
-
--- /dev/null
+#!@PYTHON@
+# create-version-itexi.py
+
+""" when being called on lilypond.org, pass it the location of the
+top source dir on the command-line. """
+
+import sys
+import os
+import glob
+
+
+
+# FIXME: if the depth depends on the type of build, figure it
+# out automatically.
+### just like depth in our GNUmakefiles
+# these links are relative from /~graham/web/
+depth = "../../"
+# these links are relative from the v2.13 docs
+#depth = "../../../../"
+
+
+
+VERSION_STABLE = ""
+VERSION_DEVEL = ""
+
+try:
+ topDir = sys.argv[1]
+except:
+ myDir = os.path.dirname(sys.argv[0])
+ # use two abspaths to work around some windows python bug
+ topDir = os.path.join(os.path.abspath(myDir)+os.sep+'..'+os.sep+'..'+os.sep)
+ topDir = os.path.abspath( topDir )
+
+
+# TODO: this might be useful for other scripts; can we make it available?
+manuals = map(lambda x: os.path.splitext(x)[0],
+ map(os.path.basename,
+ glob.glob(os.path.join(topDir,'Documentation', '*.te??'))))
+#manuals = map(lambda x: 'glossary' if x=='music-glossary' else x, manuals)
+manuals.append('internals')
+
+
+version_file_path = os.path.join(topDir, "VERSION")
+
+version_contents = open(version_file_path).readlines()
+major = 0
+minor = 0
+patch = 0
+for line in version_contents:
+ if (line.startswith('MAJOR_VERSION')):
+ major = line[14:-1]
+ if (line.startswith('MINOR_VERSION')):
+ minor = line[14:-1]
+ if (line.startswith('PATCH_LEVEL')):
+ patch = line[12:-1]
+ if (line.startswith('VERSION_STABLE')):
+ VERSION_STABLE = line[15:-1]
+ if (line.startswith('VERSION_DEVEL')):
+ VERSION_DEVEL = line[14:-1]
+
+VERSION = str(major)+'.'+str(minor)+'.'+str(patch)
+
+def make_macro(name, string):
+ print "@macro", name
+ print string
+ print "@end macro"
+ print ""
+
+def make_download(name, osA, osB, version, revision, text):
+ string = "@uref{http://download.linuxaudio.org/lilypond/binaries/"
+ string += osA + "lilypond-"
+ string += version + "-" + revision
+ string += "." + osB + ",\n"
+ string += text
+ string += ": LilyPond "
+ string += version + "-" + revision
+ string += "}"
+ make_macro(name, string)
+
+def make_download_source(name, vstring, version):
+ string = "@uref{http://download.linuxaudio.org/lilypond/sources/"
+ string += vstring + "/"
+ string += "lilypond-" + version + ".tar.gz"
+ string += ", "
+ string += "Source: lilypond-" + version + ".tar.gz"
+ string += "}"
+ make_macro(name, string)
+
+def make_all_downloads(macroName, version):
+ make_download("download"+macroName+"LinuxNormal", "linux-x86/",
+ "linux-x86.sh", version, "1", "Linux x86")
+ make_download("download"+macroName+"LinuxBig", "linux-64/",
+ "linux-64.sh", version, "1", "Linux 64")
+ make_download("download"+macroName+"LinuxPPC", "linux-ppc/",
+ "linux-ppc.sh", version, "1", "Linux PPC")
+
+ make_download("download"+macroName+"FreeBSDNormal", "freebsd-x86/",
+ "freebsd-x86.sh", version, "1", "FreeBSD i386")
+ make_download("download"+macroName+"FreeBSDBig", "freebsd-64/",
+ "freebsd-64.sh", version, "1", "FreeBSD amd64")
+
+ make_download("download"+macroName+"DarwinNormal", "darwin-x86/",
+ "darwin-x86.tar.bz2", version, "1", "MacOS X x86")
+ make_download("download"+macroName+"DarwinPPC", "darwin-ppc/",
+ "darwin-ppc.tar.bz2", version, "1", "MacOS X PPC")
+
+ make_download("download"+macroName+"Windows", "mingw/",
+ "mingw.exe", version, "1", "Windows")
+
+def make_ver_link(macroname, url, linktext):
+ string = "@uref{"
+ string += url
+ string += ","
+ string += linktext
+ string += "}"
+ make_macro(macroname, string)
+
+# TODO: this kind of thing should really be in a central place for
+# lilypond python build scripts
+def translateNameToUrl(manual, version):
+ ver_split = version.split('.')
+ ver_minor = ver_split[0] + '.' + ver_split[1]
+ url = depth + "doc/v" + ver_minor + "/Documentation/"
+
+ if (ver_minor == '2.13'):
+ return url+manual
+ if (ver_minor == '2.12'):
+ if (manual=='learning'):
+ return url+'user/lilypond-learning'
+ elif (manual=='internals'):
+ return url+'user/lilypond-internals'
+ elif (manual=='notation'):
+ return url+'user/lilypond'
+ elif (manual=='usage'):
+ return url+'user/lilypond-program'
+ elif (manual=='snippets'):
+ return url+'../input/lsr/lilypond-snippets'
+ elif (manual=='changes'):
+ return url+'topdocs/NEWS.html'
+ elif (manual=='music-glossary'):
+ return url+'user/music-glossary'
+ elif (manual=='essay'):
+ return url+'user/lilypond-learning/Background.html'
+ elif (manual=='extending'):
+ return url+'user/lilypond/Interfaces-for-programmers.html'
+ else:
+ return ''
+
+
+def make_manual_links(name, version):
+ for m in manuals:
+ manual = m
+ if (m=='music-glossary'):
+ mshort = 'Glossary'
+ else:
+ mshort = m.capitalize()
+ url = translateNameToUrl(m, version)
+
+ if (url == ''):
+ # can't have a comma here due to texinfo
+ make_ver_link("manual"+name+mshort+'Pdf',
+ "http://lilypond.org",
+ mshort+" (did not exist in 2.12)")
+ make_ver_link("manual"+name+mshort+'Split',
+ "http://lilypond.org",
+ mshort+" (did not exist in 2.12)")
+ make_ver_link("manual"+name+mshort+'Big',
+ "http://lilypond.org",
+ mshort+" (did not exist in 2.12)")
+ make_ver_link("manual"+name+mshort+'SplitNoName',
+ "http://lilypond.org",
+ mshort+" (did not exist in 2.12)")
+ continue
+ make_ver_link("manual"+name+mshort+'Pdf',
+ url + '.pdf',
+ manual.capitalize() + '.pdf')
+ make_ver_link("manual"+name+mshort+'Split',
+ url + '/index.html',
+ manual.capitalize() + ' (split HTML)')
+ make_ver_link("manual"+name+mshort+'Big',
+ url + '-big-page.html',
+ manual.capitalize() + ' (big HTML)')
+ # this is stupid and I shouldn't have bothered trying
+ # to support the 2.12 docs and it will be deleted once
+ # 2.14 is out and the website won't be visible to users
+ # until 2.14 is out. -gp
+ if (url.endswith('.html')):
+ newurl = url
+ else:
+ newurl = url + '/index.html'
+ make_ver_link("manual"+name+mshort+'SplitNoName',
+ newurl,
+ manual.capitalize())
+
+def make_regtest_links(name, version):
+ ver_split = version.split('.')
+ ver_minor = ver_split[0] + '.' + ver_split[1]
+ url = depth + "doc/v" + ver_minor + "/input/regression/"
+
+ make_ver_link("regtest"+name, url+"collated-files.html",
+ "Regression tests for "+version)
+ make_ver_link("regtest"+name+"Pdf", url+"collated-files.pdf",
+ "pdf of "+version+" regtests")
+ make_ver_link("regtest"+name+"Xml", url+"musicxml/collated-files.html",
+ "MusicXML Regression tests for "+version)
+ make_ver_link("regtest"+name+"XmlPdf", url+"musicxml/collated-files.html",
+ "pdf of "+version+" musicxml regtests")
+
+def make_doctarball_links(name, version):
+ url = depth + "download/binaries/documentation/lilypond-"
+ # ugly FIXME, but proper build number support isn't Critical.
+ url += version + "-1"
+ url += ".documentation.tar.bz2"
+ make_ver_link("doctarball"+name, url, "Doc tarball for "+version)
+
+print "@c ************************ Download binaries ************"
+make_all_downloads("Stable", VERSION_STABLE)
+make_all_downloads("Devel", VERSION_DEVEL)
+
+print "@c ************************ Download source ************"
+# FIXME: icky hard-coding! -gp
+make_download_source("downloadStableSource", "v2.12", VERSION_STABLE)
+make_download_source("downloadDevelSource", "v2.13", VERSION_DEVEL)
+
+print "@c ************************ Manual links ************"
+make_manual_links("Stable", VERSION_STABLE)
+make_manual_links("Devel", VERSION_DEVEL)
+make_doctarball_links("Stable", VERSION_STABLE)
+make_doctarball_links("Devel", VERSION_DEVEL)
+
+print "@c ************************ Regtest links ************"
+make_regtest_links("Stable", VERSION_STABLE)
+make_regtest_links("Devel", VERSION_DEVEL)
+
$(outdir)/%.texi: $(src-dir)/%.texi
cp -p $< $@
-$(outdir)/%.info: $(outdir)/%.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi
+$(outdir)/%.info: $(outdir)/%.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi $(outdir)/weblinks.itexi
ifeq ($(WEB_VERSION),yes)
$(MAKEINFO) -I$(src-dir) -I$(outdir) -D web_version --output=$@ $<
else
$(MAKEINFO) -I$(src-dir) -I$(outdir) --output=$@ $<
endif
-$(outdir)/%-big-page.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi
+$(outdir)/%-big-page.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi $(outdir)/weblinks.itexi
ifeq ($(WEB_VERSION),yes)
$(TEXI2HTML) $(TEXI2HTML_FLAGS) -D bigpage -D web_version --output=$@ $<
else
$(TEXI2HTML) $(TEXI2HTML_FLAGS) -D bigpage --output=$@ $<
endif
-$(outdir)/%.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi
+$(outdir)/%.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi $(outdir)/weblinks.itexi
$(TEXI2HTML) $(TEXI2HTML_FLAGS) --output=$@ $<
-$(outdir)/%/index.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi $(outdir)/%.html.omf
+$(outdir)/%/index.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi $(outdir)/weblinks.itexi $(outdir)/%.html.omf
mkdir -p $(dir $@)
ifeq ($(WEB_VERSION),yes)
$(TEXI2HTML) $(TEXI2HTML_SPLIT) $(TEXI2HTML_FLAGS) -D web_version --output=$(dir $@) $<
$(XREF_MAPS_DIR)/%.xref-map: $(outdir)/%.texi
$(buildscript-dir)/extract_texi_filenames $(XREF_MAP_FLAGS) -o $(XREF_MAPS_DIR) $<
-$(outdir)/%.info: %.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi
+$(outdir)/%.info: %.texi $(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep $(outdir)/version.itexi $(outdir)/weblinks.itexi
$(MAKEINFO) -I$(src-dir) -I$(outdir) --output=$@ $<
-$(outdir)/%.pdf: $(outdir)/%.texi $(outdir)/version.itexi $(outdir)/%.pdf.omf
+$(outdir)/%.pdf: $(outdir)/%.texi $(outdir)/version.itexi $(outdir)/%.pdf.omf $(outdir)/weblinks.itexi
ifeq ($(WEB_VERSION),yes)
cd $(outdir); texi2pdf $(TEXI2PDF_FLAGS) -D web_version -I $(abs-src-dir) --batch $(TEXINFO_PAPERSIZE_OPTION) $(<F)
else
cd $(outdir); texi2pdf $(TEXI2PDF_FLAGS) -I $(abs-src-dir) --batch $(TEXINFO_PAPERSIZE_OPTION) $(<F)
endif
-$(outdir)/%.txt: $(outdir)/%.texi $(outdir)/version.itexi
+$(outdir)/%.txt: $(outdir)/%.texi $(outdir)/version.itexi $(outdir)/weblinks.itexi
$(MAKEINFO) -I$(src-dir) -I$(outdir) --no-split --no-headers --output $@ $<
$(outdir)/%.html.omf: %.texi
$(outdir)/version.%: $(top-src-dir)/VERSION
$(PYTHON) $(top-src-dir)/scripts/build/create-version-itexi.py > $@
+$(outdir)/weblinks.%: $(top-src-dir)/VERSION
+ $(PYTHON) $(top-src-dir)/scripts/build/create-weblinks-itexi.py > $@
+
.SECONDARY: $(outdir)/version.itexi $(outdir)/version.texi \
$(outdir)/$(INFO_IMAGES_DIR).info-images-dir-dep \
$(outdir)/*.texi
TEXI2HTML_INCLUDES += --I=$(src-dir) --I=$(outdir) $(DOCUMENTATION_INCLUDES) --I=$(XREF_MAPS_DIR)
TEXI2HTML_FLAGS += $(TEXI2HTML_INCLUDES) $(TEXI2HTML_INIT) $(TEXI2HTML_LANG)
-TEXI2HTML = TOP_SRC_DIR=$(top-src-dir) PERL_UNICODE=SD $(TEXI2HTML_PROGRAM)
+TEXI2HTML = TOP_SRC_DIR=$(top-src-dir) DEPTH=$(depth) PERL_UNICODE=SD $(TEXI2HTML_PROGRAM)
###########
ifeq ($(WEBSITE_ONLY_BUILD),1)
### for lilypond.org
top-src-dir=$(HOME)/src/lilypond
+ depth=.
trusted-dir=$(HOME)/lilypond/trusted-scripts
script-dir=$(trusted-dir)
texi2html-init-file=$(trusted-dir)/lilypond-texi2html.init
################################################################
OUT=out-website
-TEXI2HTML = TOP_SRC_DIR=$(top-src-dir) PERL_UNICODE=SD $(TEXI2HTML_PROGRAM)
+TEXI2HTML=TOP_SRC_DIR=$(top-src-dir) DEPTH=$(depth) PERL_UNICODE=SD $(TEXI2HTML_PROGRAM)
EXTRACT_TEXI_FILENAMES=python $(script-dir)/extract_texi_filenames.py
CREATE_VERSION=python $(script-dir)/create-version-itexi.py
+CREATE_WEBLINKS=python $(script-dir)/create-weblinks-itexi.py
# don't include web
website-version:
mkdir -p $(OUT)
$(CREATE_VERSION) $(top-src-dir) > $(OUT)/version.itexi
+ $(CREATE_WEBLINKS) $(top-src-dir) > $(OUT)/weblinks.itexi
website-xrefs: website-version
$(EXTRACT_TEXI_FILENAMES) -I $(top-src-dir)/Documentation/ \
projects / lilypond.git / commitdiff