@c -*- coding: us-ascii; mode: texinfo; -*-
+
@node Compiling LilyPond
@chapter Compiling LilyPond
+@menu
+* Compiling from source::
+* Concurrent Stable and Development Versions::
+@end menu
-TODO: ADD
+@node Compiling from source
+@section Compiling from source
-- how to make a stable version and development version coexist on
- your system
+TODO (see AU 1 for now)
+@c currently broken; will fix after 2.14
+@c @include compile.itely
-@node move AU 1 here
-@section move AU 1 here
-- other compilation tricks for developers
+@node Concurrent Stable and Development Versions
+@section Concurrent Stable and Development Versions
-@menu
-* Compiling from source:: standard compilation instructions
-@end menu
+It can be useful to have both the stable and the development versions
+of Lilypond available at once. One way to do this on GNU/Linux is to
+install the stable version using the precompiled binary, and run the
+development version from the source tree. After running @command{make
+all} from the top directory of the Lilypond source files, there will
+be a binary called @code{lilypond} in the @code{out} directory:
+
+@example
+<@var{path to}>/lilypond/out/bin/lilypond
+@end example
+
+This binary can be run without actually doing the @code{make
+install} command. The advantage to this is that you can have all
+of the latest changes available after pulling from git and running
+@code{make all}, without having to uninstall the old version and
+reinstall the new.
+
+So, to use the stable version, install it as usual and use the
+normal commands:
+
+@example
+lilypond foobar.ly
+@end example
+
+To use the development version, create a link to the binary in the
+source tree by saving the following line in a file somewhere in your
+PATH:
+
+@example
+exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
+@end example
+
+Save it as @code{Lilypond} (with a capital L to distinguish it
+from the stable @code{lilypond}), and make it executable:
+
+@example
+chmod +x Lilypond
+@end example
+
+Then you can invoke the development version this way:
+
+@example
+Lilypond foobar.ly
+@end example
+
+
+TODO: ADD
+
+- how to build with debug info
+
+- other compilation tricks for developers
-@include compile.itely
@afourpaper
-@c Keep this here, since it pertains to the direntry below.
-@ignore
-Distributions will want to install lilypond.info in postinstall, doing:
-
- install-info --info-dir=/usr/share/info out[-www]/lilypond.info
-
- * Prepend GNU for dir, must be unique.
-
- * Do not list the `lilypond' node at toplevel, so that `info lilypond'
- goes to Top.
-
- * List all commands in direntry.
-
-@c * lilypond: (lilypond/lilypond)Running LilyPond. Invoking the
-@c LilyPond program.
-@end ignore
-
-
@ifnottex
@node Top
@top GNU LilyPond --- Contributor's Guide
@chapheading The music typesetter
-@c HJJ: Info needs `@top', which is a synonym for `@unnumbered' in TeX.
@end ifnottex
@ifhtml
@ifclear bigpage
This document is also available as a
-@uref{source/Documentation/user/lilypond.pdf,PDF} and as
-@uref{source/Documentation/user/lilypond-big-page.html,one big page}.
+@uref{source/Documentation/devel/contrib-guide.pdf,PDF} and as
+@c FIXME: update @uref{} stuff.
+@uref{source/Documentation/devel/,one big page}.
@end ifclear
@ifset bigpage
This document is also available as a
-@uref{source/Documentation/user/lilypond.pdf,PDF} and as a
-@uref{source/Documentation/user/lilypond/index.html,HTML indexed multiple pages}.
+@uref{source/Documentation/devel/contrib-guide.pdf,PDF} and as a
+@uref{source/Documentation/devel/contrib-guide/index.html,HTML indexed multiple pages}.
@end ifset
@end ifhtml
@vskip 20pt
-For LilyPond version
+For LilyPond version
@end titlepage
@end iftex
@end copying
@ifnottex
-This file documents GNU LilyPond.
+This file documents contributing to GNU LilyPond.
Copyright 1999--2008 by the authors
@end ifnottex
@ifnottex
-For more information about how this fits with the other
-
-@cindex web site
-@cindex URL
More information can be found at
-@uref{http://@/www@/.lilypond@/.org/}. The website contains on-line copies
-of this and other documentation.
+@uref{http://@/www@/.lilypond@/.org/}. The website contains
+on-line copies of this and other documentation.
@menu
* Starting with git::
@example
-1- Documentation index and Tutorial
429 user/lilypond-learning.tely
-6365 user/tutorial.itely
+6343 user/tutorial.itely
23 user/dedication.itely
-423 user/macros.itexi
+432 user/macros.itexi
171 index.html.in
-6346 po/lilypond-doc.pot (translate to po/@var{MY_LANGUAGE}.po)
+161 translations.template.html.in
+6438 po/lilypond-doc.pot (translate to po/@var{MY_LANGUAGE}.po)
--- ../lilypond-texi2html.init (section TRANSLATIONS)
-13757 total
+13997 total
-2- Introduction and beginning of Application Usage
411 user/preface.itely
3855 user/introduction.itely
407 user/lilypond-program.tely
-1928 user/install.itely (partial translation)
+193 user/install.itely (partial translation)
1149 user/setup.itely
2827 user/running.itely
-10577 total
+8842 total
-3- Learning manual
10318 user/fundamental.itely -- Fundamental concepts
-14775 user/tweaks.itely -- Tweaking output
-3007 user/working.itely -- Working on LilyPond files
-483 user/templates.itely -- Templates
-28583 total
+14816 user/tweaks.itely -- Tweaking output
+4550 user/working.itely -- Working on LilyPond files
+498 user/templates.itely -- Templates
+30182 total
-4- Notation reference
-695 user/lilypond.tely
+724 user/lilypond.tely
91 user/notation.itely -- Musical notation
-3123 user/pitches.itely
-5236 user/rhythms.itely
-1146 user/expressive.itely
+3145 user/pitches.itely
+4772 user/rhythms.itely
+1393 user/expressive.itely
555 user/repeats.itely
-1455 user/simultaneous.itely
-1701 user/staff.itely
-895 user/editorial.itely
-2286 user/text.itely
+1456 user/simultaneous.itely
+1708 user/staff.itely
+905 user/editorial.itely
+2376 user/text.itely
76 user/specialist.itely -- Specialist notation
-2670 user/vocal.itely
-1464 user/chords.itely
+2725 user/vocal.itely
+1516 user/chords.itely
702 user/piano.itely
810 user/percussion.itely
826 user/guitar.itely
66 user/strings.itely
242 user/bagpipes.itely
4487 user/ancient.itely
-5873 user/input.itely -- Input syntax
+6024 user/input.itely -- Input syntax
2164 user/non-music.itely -- Non-musical notation
-8451 user/spacing.itely -- Spacing issues
-11391 user/changing-defaults.itely -- Changing defaults
-5202 user/programming-interface.itely -- Interfaces for programmers
-1190 user/notation-appendices.itely -- Notation manual tables
-250 user/cheatsheet.itely -- Cheat sheet
-63047 total
+8663 user/spacing.itely -- Spacing issues
+11747 user/changing-defaults.itely -- Changing defaults
+5187 user/programming-interface.itely -- Interfaces for programmers
+1182 user/notation-appendices.itely -- Notation manual tables
+252 user/cheatsheet.itely -- Cheat sheet
+63794 total
-5- Application usage
3248 user/lilypond-book.itely -- LilyPond-book
@chapter Documentation work
@menu
-* Introduction to documentation work::
-* Texinfo introduction and usage policy::
-* Documentation policy::
-* Tips for writing docs::
-* Updating docs with convert-ly::
-* Translating the documentation::
+* Introduction to documentation work::
+* Documentation suggestions::
+* Texinfo introduction and usage policy::
+* Documentation policy::
+* Tips for writing docs::
+* Updating docs with convert-ly::
+* Translating the documentation::
@end menu
limited documentation help.
+@node Documentation suggestions
+@section Documentation suggestions
+
+@subheading Small additions
+
+For additions to the documentation,
+
+@enumerate
+
+@item
+Tell us where the addition should be placed. Please include both
+the section number and title (i.e. "LM 2.13 Printing lyrics").
+
+@item
+Please write exact changes to the text.
+
+@item
+A formal patch to the source code is @emph{not} required; we can
+take care of the technical details. Here is an example of a
+perfect documentation report:
+
+@verbatim
+To: lilypond-devel@gnu.org
+From: helpful-user@example.net
+Subject: doc addition
+
+In LM 2.13 (printing lyrics), above the last line ("More options,
+like..."), please add:
+
+----
+To add lyrics to a divided part, use blah blah blah. For example,
+
+\score {
+ \notes {blah <<blah>> }
+ \lyrics {blah <<blah>> }
+ blah blah blah
+}
+----
+
+In addition, the second sentence of the first paragraph is
+confusing. Please delete that sentence (it begins "Users
+often...") and replace it with this:
+----
+To align lyrics with something, do this thing.
+----
+
+Have a nice day,
+Helpful User
+@end verbatim
+
+@end enumerate
+
+
+@subheading Larger contributions
+
+To replace large sections of the documentation, the guidelines are
+stricter. We cannot remove parts of the current documentation
+unless we are certain that the new version is an improvement.
+
+@enumerate
+
+@item
+Ask on the lilypond-devel maillist if such a rewrite is necessary;
+somebody else might already be working on this issue!
+
+@item
+Split your work into small sections; this makes it much easier to
+compare the new and old documentation.
+
+@item
+Please prepare a formal git patch.
+
+@end enumerate
+
+Once you have followed these guidelines, please send a message to
+lilypond-devel with your documentation submissions. Unfortunately
+there is a strict “no top-posting” check on the mailist; to avoid
+this, add:
+
+> I'm not top posting.
+
+(you must include the > ) to the top of your documentation
+addition.
+
+We may edit your suggestion for spelling, grammar, or style, and
+we may not place the material exactly where you suggested, but if
+you give us some material to work with, we can improve the manual
+much faster. Thanks for your interest!
+
@node Texinfo introduction and usage policy
@section Texinfo introduction and usage policy
@menu
-* Texinfo introduction::
-* Sectioning commands::
-* LilyPond formatting::
-* Text formatting::
-* Syntax survey::
-* Other text concerns::
+* Texinfo introduction::
+* Documentation files::
+* Sectioning commands::
+* LilyPond formatting::
+* Text formatting::
+* Syntax survey::
+* Other text concerns::
@end menu
to do anything fancy, discuss it on @code{lilypond-devel} first.}
+@node Documentation files
+@subsection Documentation files
+
+The user manuals lives in @file{Documentation/user/}. In
+particular, the files @file{lilypond-learning.ly} (LM),
+@file{lilypond.itely} (NR), @file{music-glossary.tely} (MG), and
+@file{lilypond-program} (AU). Each chapter is written in a
+separate file (ending in @file{.itely} for files containing
+lilypond code, and @file{.itexi} for files without lilypond code);
+see the @qq{main} file for each manual to determine the filename
+of the specific chapter you wish to modify.
+
+Developer manuals live in @file{Documentation/devel}. Currently
+there is only one; @file{contrib-guide.texi}.
+
+Although snippets are part of documentation, they are not
+(directly) part of the manuals. For information about how to
+modify them, see @ref{LSR work}.
+
+
+@node Sectioning commands
@subsection Sectioning commands
Most of the manual operates at the
@end itemize
-
+@node LilyPond formatting
@subsection LilyPond formatting
@itemize
@end itemize
+@node Text formatting
@subsection Text formatting
@itemize
@end itemize
+@node Syntax survey
@subsection Syntax survey
@itemize
@item
@@bs - Generates a backslash inside @@warning.
- Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
+ Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
(texinfo would also allow \\, but this breaks with PDF output).
+@item
+@@ref@{@} - normal references (type the exact node name inside the
+@{@}).
+@item
+@@ruser@{@} - link to the NR.
+@item
+@@rlearning@{@} - link to the LM.
+@item
+@@rglos@{@} - link to the MG.
+@item
+@@rprogram@{@} - link to the AU.
+@item
+@@rlsr@{@} - link to a Snippet section.
+@item
+@@rinternals@{@} - link to the IR.
+@item
+@@uref@{@} - link to an external url.
+
@end itemize
+@node Other text concerns
@subsection Other text concerns
@itemize
@node Documentation policy
@section Documentation policy
+@menu
+* Books::
+* Section organization::
+* Checking cross-references::
+* General writing::
+* Technical writing style::
+@end menu
+@node Books
@subsection Books
There are four parts to the documentation: the Learning Manual,
@end itemize
+@node Section organization
@subsection Section organization
@itemize
@end itemize
+@node Checking cross-references
@subsection Checking cross-references
Cross-references between different manuals are heavily used in the
Internals Reference; e.g. you can grep scm/ and lily/.
+@node General writing
@subsection General writing
@itemize
@end itemize
+@node Technical writing style
@subsection Technical writing style
These refer to the NR. The LM uses a more gentle, colloquial
harder than it looks.
-@subsubheading TWEAKS
+@subsubheading Tweaks
In general, any \set or \override commands should go in the
@qq{select snippets} section, which means that they should go in
would be ideal if every significant known issue had a workaround to avoid
the difficulty.
+@seealso
+
+@ref{Adding and editing snippets}.
+
@node Updating docs with convert-ly
@section Updating doc with @command{convert-ly}
@section Translating the documentation
@menu
-* Getting started with documentation translation::
-* Documentation translation details::
-* Documentation translation maintenance::
-* Translations management policies::
-* Technical background::
+* Getting started with documentation translation::
+* Documentation translation details::
+* Documentation translation maintenance::
+* Translations management policies::
+* Technical background::
+* Translation status::
@end menu
@node Getting started with documentation translation
translations source code}.
@menu
-* Translation requirements::
-* Which documentation can be translated::
-* Starting translation in a new language::
+* Translation requirements::
+* Which documentation can be translated::
+* Starting translation in a new language::
@end menu
@node Translation requirements
All files should be encoded in UTF-8.
@menu
-* Files to be translated::
-* Translating the Learning Manual and other Texinfo documentation::
-* Translating the Notation Reference and Application Usage::
-* Translating the Documentation index index.html.in::
+* Files to be translated::
+* Translating the Learning Manual and other Texinfo documentation::
+* Translating the Notation Reference and Application Usage::
+* Translating the Documentation index index.html.in::
@end menu
@node Files to be translated
@@section @@unnumberedsec @@appendixsec @@heading
@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
-@@ref @@rglos
+@@ref @@rglos @@ruser @@rlearning @@rprogram @@rlsr
@end example
-As a notable exception, the second argument @var{Bar baz} of
-@code{@@ref@{@var{Foo},@var{Bar baz},,@var{info-file}@}} should be
+The same applies to first argument of @code{@@r@var{manual}named}
+commands; however, the second argument @var{Bar baz} of
+@code{@@ref@{@var{Foo},@var{Bar baz},,@var{info-file}@}} and
+@code{@@r@var{manual}named@{@var{Foo},@var{Bar baz}@}} should be
translated.
@code{@@uref}'s names are to be translated.
version control system used for LilyPond development.
@menu
-* Check state of translation::
-* Updating documentation translation::
+* Check state of translation::
+* Updating documentation translation::
@end menu
@node Check state of translation
coordinators work efficiently.
@menu
-* Maintaining without updating translations::
-* Managing documentation translation with Git::
+* Maintaining without updating translations::
+* Managing documentation translation with Git::
@end menu
@node Maintaining without updating translations
@noindent
This step requires a sucessful documentation build (with @command{make
-web}). Some cross-references are broken because they point to a node
+doc}). Some cross-references are broken because they point to a node
that exists in the documentation in English, which has not been added
to the translation; in this case, do not fix the cross-reference but
keep it "broken", so that the resulting HTML link will point to an
@code{stable/X.Y} are preferably made on
@code{lilypond/X.Ytranslation}.
-@item @code{lilypond/translation} Git branch may be merged into master only if
-LilyPond (@command{make all}) and documentation (@command{make web}) compile
-succesfully.
+@item @code{lilypond/translation} Git branch may be merged into
+master only if LilyPond (@command{make all}) and documentation
+(@command{make doc}) compile succesfully.
@item @code{master} Git branch may be merged into
@code{lilypond/translation} whenever @command{make} and @command{make
-web} are succesful (in order to ease documentation compilation by
+doc} are succesful (in order to ease documentation compilation by
translators), or when significant changes had been made in
documentation in English in master branch.
@itemize
@item @file{python/langdefs.py} -- language definitions module
@end itemize
+
+
+@node Translation status
+@subsection Translation status
+
+
To complete or present in another form the introduction to Git usage
in this chapter, it may be a good idea to look for Git documentation
-at @uref{http://git-scm.com/documentation},
+at @uref{http://git-scm.com/documentation},
@menu
-* Getting the source code::
-* Updating the source code::
-* Working with several Git branches::
-* Sharing your changes::
-* Other interesting Git commands::
-* Git on Windows::
+* Getting the source code::
+* Updating the source code::
+* Sharing your changes::
+* Advanced git stuff::
+* Git on Windows::
@end menu
@section Getting the source code
@menu
-* Git introduction::
-* Main source code::
-* Website source code::
-* Documentation translations source code::
-* Other branches::
-* Other locations for git::
-* Git user configuration::
+* Git introduction::
+* Main source code::
+* Website source code::
+* Documentation translations source code::
+* Other branches::
+* Other locations for git::
+* Git user configuration::
@end menu
@node Git introduction
@item @code{gub}:
This stores the Grand Unified Binary, our cross-platform building
-tool. For more info, see @uref{http://lilypond.org/gub}. The git
+tool.
+@c TODO: merge the gub stuff with this CG.
+For more info, see @uref{http://lilypond.org/gub}. The git
location is:
@example
listed in earlier sections, try:
@example
-git://git.sv.gnu.org/lilypond.git
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
@example
git config --global user.name "MYNAME"
-git config --global user.email myemail@@example.net
+git config --global user.email MYEMAIL@@EXAMPLE.NET
@end example
@section Updating the source code
@menu
-* Importance of updating::
-* Update command::
-* Resolving conflicts::
-* Introduction to Git concepts::
+* Importance of updating::
+* Update command::
+* Resolving conflicts::
@end menu
the remote @code{git.sv.gnu.org} repository:
@example
-git pull origin
+git pull -r
@end example
@subsection Resolving conflicts
Occasionally an update may result in conflicts -- this happens
-when you and somebody else hae modified the same part of the same
+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.
resolve conflicts} in @command{git merge} man page.
+@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 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.
+
+
+@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, then go to
+@q{Preferences} then to something like @q{Edit SSH Keys}, and follow
+the instructions on that page.
+
+You may then:
+
+@example
+git push origin
+@end example
+
+@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::
+* Applying git patches::
+@end menu
+
+
@node Introduction to Git concepts
@subsection Introduction to Git concepts
methods or just understand how it works.
-@node Working with several Git branches
-@section Working with several Git branches
-
-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
-* Git commands for managing several branches::
-* Working on LilyPond sources with several branches::
-@end menu
-
@node Git commands for managing several branches
@subsection Git commands for managing several branches
repository.
-@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 HEAD
-@end example
-
-Send an email to @email{lilypond-devel@@gnu.org} with the diff as
-an attachment.
-
-
-@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, then go to
-@q{Preferences} then to something like @q{Edit SSH Keys}, and follow
-the instructions on that page.
-
-You may then
-
-@example
-git push origin
-@end example
-
-
-@node Other interesting Git commands
-@section Other interesting Git commands
-
-@menu
-* Git log::
-* Applying git patches::
-@end menu
-
@node Git log
@subsection Git log
Well-formed git patches should be committed with
@example
-git-am
+git am
@end example
-Patches created without @code{git-format-patch} should be
+Patches created without @code{git format-patch} should be
committed with
@example
-git-apply
+git apply
@end example
@subsection Installing git
Obtain Git from
-@uref{http://code.google.com/p/msysgit/downloads/list}.
-(Note, not msysGit, which is for Git developers) and
-install.
+@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
call the folder to contain the repository [path]/Git.
You will need to have space for around 150Mbytes.
-In the git bash shell type
+Start the Git bash shell by clicking on the desk-top icon installed
+with Git and type
@example
cd [path]/Git
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,
if necessary, then produce the patch with
@example
-git-format-patch -n
+git format-patch origin
@end example
-where n an integer, normally 1. This will create a
-patch file for all the locally committed files which differ
-from @w{origin/master}. The patch file can be found in
-[path]/Git and will have a name formed from n and the
-commit message.
+This will create a patch file for all the locally committed files
+which differ from @w{origin/master}. The patch file can be found
+in [path]/Git and will have a name formed from n and the commit
+message.
@subsection Resolving merge conflicts
@chapter LSR work
@menu
-* Introduction to LSR::
-* Adding snippets::
-* Approving snippets::
-* LSR to git::
+* Introduction to LSR::
+* Adding and editing snippets::
+* Approving snippets::
+* LSR to Git::
+* Fixing snippets in LilyPond sources::
+* Updating LSR to a new version::
@end menu
@node Introduction to LSR
@section Introduction to LSR
+The
+@uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
+is a collection of lilypond examples. A subset of these examples
+are automatically imported into the documentation, making it easy
+for users to contribute to the docs without learning Git and
+Texinfo.
-@node Adding snippets
-@section Adding snippets
+
+@node Adding and editing snippets
+@section Adding and editing snippets
+
+@subheading General guidelines
+
+When you create (or find!) a nice snippet, if it supported by LilyPond
+version running on LSR, please add it to LSR. Go to
+@uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't
+already, create an account. Follow the instructions on the website.
+These instructions also explain how to modify existing snippets.
+
+If you think the snippet is particularly informative and you think it
+should be included in the documentation, tag it with @qq{docs} and one
+or more other categories, or ask somebody who has editing permissions to
+do it on the development list.
+
+Please make sure that the lilypond code follows the guidelines in
+@ref{LilyPond formatting}.
+
+If a new snippet created for documentation purposes compiles with
+LilyPond version currently on LSR, it should be added to LSR, and a
+reference to the snippet should be added to the documentation.
+
+If the new snippet uses new features that are not available in the
+current LSR version, the snippet should be added to @file{input/new} and
+a reference should be added to the manual.
+
+Snippets created or updated in @file{input/new} should be copied to
+@file{input/lsr} by invoking at top of the source tree
+
+@example
+scripts/auxiliar/makelsr.py
+@end example
+
+Be sure that @command{make doc} runs successfully before submitting a
+patch, to prevent breaking compilation.
+
+@subheading Formatting snippets in @file{input/new}
+
+When adding a file to this directory, please start the file with
+
+@example
+\version "2.x.y"
+\header @{
+ lsrtags = "rhythms,expressive-marks" % use existing LSR tags other than
+% 'docs'; see makelsr.py for the list of tags used to sort snippets.
+ texidoc = "This code demonstrates ..." % this will be formated by Texinfo
+ doctitle = "Snippet title" % please put this at the end so that
+ the '% begin verbatim' mark is added correctly by makelsr.py.
+@}
+@end example
+
+and name the file @file{snippet-title.ly}.
@node Approving snippets
@section Approving snippets
+The main task of LSR editors is approving snippets. To find a list of
+unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
+select @qq{No} from the dropdown menu to the right of the word
+@qq{Approved} at the bottom of the interface, then click
+@qq{Enable filter}.
+
+Check each snippet:
+
+@enumerate
+
+@item
+Does the snippet make sense and does what the author claims that
+it does? If you think the snippet is particularly helpful, add
+the @qq{docs} tag and at least one other tag.
+
+@item
+If the snippet is tagged with @qq{docs}, check to see if it
+matches our guidelines for @ref{LilyPond formatting}.
+
+@item
+If the snippet uses scheme, check that everything looks good and
+there are no security risks.
+
+@warning{Somebody could sneak a @code{#'(system "rm -rf /")}
+command into our source tree if you do not do this! Take this
+step @strong{VERY SERIOUSLY}.}
+
+@end enumerate
+
+
+@node LSR to Git
+@section LSR to Git
+
+@enumerate
+
+@item
+Make sure that @command{convert-ly} and @command{lilypond} commands in
+current PATH are in a bleeding edge version -- latest release from
+master branch, or even better a fresh snapshot from Git master branch.
+
+@item
+From the top source directory, run:
+
+@example
+wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
+tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
+scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
+@end example
+
+@noindent
+where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
+
+@item
+Follow the instructions printed on the console to manually check for
+unsafe files.
+
+@warning{Somebody could sneak a @code{#'(system "rm -rf /")}
+command into our source tree if you do not do this! Take this
+step @strong{VERY SERIOUSLY}.}
+
+@item
+Do a git add / commit / push.
+
+@end enumerate
+
+Note that whenever there is one snippet from @file{input/new} and the
+other from LSR with the same file name, the one from @file{input/new}
+will be copied by @command{makelsr.py}.
+
+
+@node Fixing snippets in LilyPond sources
+@section Fixing snippets in LilyPond sources
+
+In case some snippet from @file{input/lsr} cause the documentation
+compilation to fail, the following steps should be followed to fix it
+reliably.
+
+@enumerate
+
+@item
+Look up the snippet filename @file{@var{foo}.ly} in the error output
+or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
+documentation build succesfully.
+
+@item
+Determine where it comes from by looking at its first line, e.g. run
+
+@example
+head -1 input/lsr/@var{foo}.ly
+@end example
+
+@item
+@strong{In case the snippet comes from LSR}, apply the fix to the
+snippet in LSR and send a notification email to a LSR editor with CC
+to the development list -- see @ref{Adding and editing snippets}. The
+failure may sometimes not be caused by the snippet in LSR but by the
+syntax conversion made by @command{convert-ly}; in this case, try to
+fix @command{convert-ly} or report the problem on the development
+list, then run @command{makelsr.py} again, see @ref{LSR to Git}. In
+some cases, when some features has been introduced or vastly changed
+so it requires (or takes significant advantage of) important changes
+in the snippet, it is simpler and recommended to write a new version
+of the snippet in @file{input/new}, then run @command{makelsr.py}.
+
+@item
+@strong{In case the snippet comes from} @file{input/new}, apply in
+@file{input/new/@var{foo}.ly} the same fix you did in
+@file{input/lsr/@var{foo}.ly}. In case the build failure was caused
+by a translation string, you may have to fix
+@file{input/texidocs/@var{foo}.texidoc} instead.
+
+@item
+In any case, commit all changes to Git.
+
+@end enumerate
+
+
+
+@node Updating LSR to a new version
+@section Updating LSR to a new version
+
+To update LSR, perform the following steps:
+
+@enumerate
+
+@item
+Download the latest snippet tarball, extract it, and run
+@code{convert-ly} on all files using the command-line option
+@code{--to=VERSION} to ensure snippets are updated to the
+correct stable version.
+
+@item
+Copy relevant snippets (i.e., snippets whose version is equal to or
+less than the new version of LilyPond) from @file{input/new/} into
+the tarball.
+
+You must not rename any files during this, or the next, stage.
+
+@item
+Verify that all files compile with the new version of LilyPond,
+ideally without any warnings or errors. To ease the process,
+you may use the shell script that appears after this list.
+
+Due to the workload involved, we @emph{do not} require that you
+verify that all snippets produce the expected output. If you
+happen to notice any such snippets and can fix them, great; but as
+long as all snippets compile, don't delay this step due to some
+weird output. If a snippet is broken, the hordes of willing
+web-2.0 volunteers will fix it. It's not our problem.
+
+@item
+Create a tarball and send it back to Sebastiano.
+
+@item
+When LSR has been updated, download another snippet tarball,
+verify that the relevant snippets from @file{input/new/} were
+included, then delete those snippets from @file{input/new/}.
+
+@end enumerate
+
+
+Here is a shell script to run all @code{.ly} files in a directory
+and redirect terminal output to text files, which are then
+searched for the word "failed" to see which snippets do not compile.
-@node LSR to git
-@section LSR to git
+@example
+#!/bin/bash
+for LILYFILE in *.ly
+do
+ STEM=$(basename "$LILYFILE" .ly)
+ echo "running $LILYFILE..."
+ lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt
+done
+grep failed *.txt
+@end example
-@c -*- coding: us-ascii; mode: texinfo; -*
-de
+@c -*- coding: us-ascii; mode: texinfo; -*-
@node Programming work
@chapter Programming work
@menu
-* Introduction to programming::
-* Programming without compiling::
-* Finding functions::
-* Code style::
-* Debugging LilyPond::
+* Overview of LilyPond architecture::
+* LilyPond programming languages::
+* Programming without compiling::
+* Finding functions::
+* Code style::
+* Debugging LilyPond::
@end menu
+@node Overview of LilyPond architecture
+@section Overview of LilyPond architecture
-@node Introduction to programming
-@section Introduction to programming
+LilyPond processes the input file into graphical and musical output in a
+number of stages. This process, along with the types of routines that
+accomplish the various stages of the process, is described in this section. A
+more complete description of the LilyPond architecture and internal program
+execution is found in Erik Sandberg's
+@uref{http://lilypond.org/web/images/thesis-erik-sandberg.pdf, master's
+thesis}.
-FIXME -- decide what goes in here and put it here. I'm not sure what
-should be here -- CDS
+
+The first stage of LilyPond processing is @emph{parsing}. In the parsing
+process, music expressions in LilyPond input format are converted to music
+expressions in Scheme format. In Scheme format, a music expression is a list
+in tree form, with nodes that indicate the relationships between various music
+events. The LilyPond parser is written in Bison.
+
+The second stage of LilyPond processing is @emph{iterating}. Iterating
+assigns each music event to a context, which is the environment in which the
+music will be finally engraved. The context is responsible for all further
+processing of the music. It is during the iteration stage that contexts are
+created as necessary to ensure that every note has a Voice type context (e.g.
+Voice, TabVoice, DrumVoice, CueVoice, MensuralVoice, VaticanaVoice,
+GregorianTranscriptionVoice), that the Voice type contexts exist in
+appropriate Staff type contexts, and that parallel Staff type contexts exist
+in StaffGroup type contexts. In addition, during the iteration stage each
+music event is assigned a moment, or a time in the music when the event
+begins.
+
+Each type of music event has an associated iterator. Iterators are defined in
+*-iterator.cc. During iteration, an
+event's iterator is called to deliver that music event to the appropriate
+context(s).
+
+The final stage of LilyPond processing is @emph{translation}. During
+translation, music events are prepared for graphical or midi output. The
+translation step is accomplished by translators or engravers (the distinction
+is unclear).
+
+Translators are defined in C++ files named *-engraver.cc. In *-engraver.cc, a
+C++ class of Engraver type is created. The Engraver is also declared as a
+translator. Much of the work of translating is handled by Scheme functions,
+which is one of the keys to LilyPond's exceptional flexibility.
+
+
+@node LilyPond programming languages
+@section LilyPond programming languages
+
+Programming in LilyPond is done in a variety of programming languages. Each
+language is used for a specific purpose or purposes. This section describes
+the languages used and provides links to reference manuals and tutorials for
+the relevant language.
+
+@subsection C++
+
+The core functionality of LilyPond is implemented in C++.
+
+C++ is so ubiquitous that it is difficult to identify either a reference
+manual or a tutorial. Programmers unfamiliar with C++ will need to spend some
+time to learn the language before attempting to modify the C++ code.
+
+The C++ code calls Scheme/GUILE through the GUILE interface, which is
+documented in the
+@uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE
+ Reference Manual}.
+
+@subsection GNU Bison
+
+The LilyPond parser is implemented in Bison, a GNU parser generator. The
+Bison homepage is found at @uref{http://www.gnu.org/software/bison/,
+gnu.org}. The manual (which includes both a reference and tutorial) is
+@uref{http://www.gnu.org/software/bison/manual/index.html, available} in a
+variety of formats.
+
+@subsection GNU Make
+
+GNU Make is used to control the compiling process and to build the
+documentation and the website. GNU Make documentation is available at
+@uref{http://www.gnu.org/software/make/manual/, the GNU website}.
+
+@subsection GUILE or Scheme
+
+GUILE is the dialect of Scheme that is used as LilyPond's extension language. Many extensions to LilyPond are written entirely in GUILE. The
+@uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
+GUILE Reference Manual} is available online.
+
+@uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and
+Interpretation of Computer Programs}, a popular textbook used to teach
+programming in Scheme is available in its entirety online.
+
+An introduction to Guile/Scheme as used in LilyPond can be found in the
+Learning Manual, see @rlearning{Scheme tutorial}.
+
+@subsection MetaFont
+
+MetaFont is used to create the music fonts used by LilyPond. A MetaFont
+tutorial is available at @uref{http://metafont.tutorial.free.fr/, the
+METAFONT tutorial page}.
+
+@subsection PostScript
+
+PostScript is used to generate graphical output. A brief PostScript tutorial
+is @uref{http://local.wasp.uwa.edu.au/~pbourke/dataformats/postscript/,
+available online}. The
+@uref{http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf, PostScript Lanugage
+Reference} is available online in PDF format.
+
+@subsection Python
+
+Python is used for XML2ly and is used for buillding the documentation and the
+website.
+
+Python documentation is available at @uref{http://www.python.org/doc/,
+python.org}.
@node Programming without compiling
@section Programming without compiling
@section Finding functions
When making changes or fixing bugs in LilyPond, one of the initial
-challenges is finding out where in the code tree the functions to be
-modified live. With nearly 3000 files in the source tree,
-trial-and-error searching is generally inefective. This section describes
-a process for finding interesting code.
+challenges is finding out where in the code tree the functions to
+be modified live. With nearly 3000 files in the source tree,
+trial-and-error searching is generally ineffective. This section
+describes a process for finding interesting code.
@subsection Using the ROADMAP
Having identified a likely subdirectory to search, the grep utility can
be used to search for a function name. The format of the grep command is
-@example
-grep functionName subdirectory/*
+@example
+grep -i functionName subdirectory/*
@end example
This command will search all the contents of the directory subdirectory/
-and display every line in any of the files that contains functionName.
+and display every line in any of the files that contains
+functionName. The @code{-i} option makes @command{grep} ignore
+case -- this can be very useful if you are not yet familiar with
+our capitalization conventions.
The most likely directories to grep for function names are scm/ for
scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
-files.
+files.
@subsection Using git grep to search
@node Code style
-@section Code style
+@section Code style
@c email to wl@gnu.org when I get here.
@menu
@subsection Classes and Types
@verbatim
- This_is_a_class
+This_is_a_class
@end verbatim
Member variable names end with an underscore:
@verbatim
- Type Class::member_
+Type Class::member_
@end verbatim
@item
Messages to be localised must be encapsulated in `_ (STRING)' or
-`_f (FORMAT, ...)'. Eg:
+`_f (FORMAT, ...)'. E.g.:
+
+@example
+warning (_ ("need music in a score"));
+error (_f ("cannot open file: `%s'", file_name));
+@end example
-@verbatim
- warning (_ ("need music in a score"));
- error (_f ("cannot open file: `%s'", file_name));
-@end verbatim
-
In some rare cases you may need to call `gettext ()' by hand. This
happens when you pre-define (a list of) string constants for later
use. In that case, you'll probably also need to mark these string
constants for translation, using `_i (STRING)'. The `_i' macro is
a no-op, it only serves as a marker for `xgettext'.
-@verbatim
- char const* messages[] = {
- _i ("enable debugging output"),
- _i ("ignore lilypond version"),
- 0
- };
-
-
- void
- foo (int i)
- {
- puts (gettext (messages i));
- }
-@end verbatim
-
+@example
+char const* messages[] = @{
+ _i ("enable debugging output"),
+ _i ("ignore lilypond version"),
+ 0
+@};
+
+void
+foo (int i)
+@{
+ puts (gettext (messages i));
+@}
+@end example
+
See also `flower/getopt-long.cc' and `lily/main.cc'.
@item
whitespace to be printed, prepend or append it to the translated
message
-@verbatim
- message (Calculating line breaks... + " ");
-@end verbatim
-
+@example
+message ("Calculating line breaks..." + " ");
+@end example
+
@item
Error or warning messages displayed with a file name and line
number never start with a capital, eg,
-@verbatim
- foo.ly: 12: not a duration: 3
-@end verbatim
-
+@example
+foo.ly: 12: not a duration: 3
+@end example
+
Messages containing a final verb, or a gerund (`-ing'-form) always
start with a capital. Other (simpler) messages start with a
lowercase letter
-@verbatim
- Processing foo.ly...
- `foo': not declared.
- Not declaring: `foo'.
-@end verbatim
-
+@example
+Processing foo.ly...
+`foo': not declared.
+Not declaring: `foo'.
+@end example
+
@item
Avoid abbreviations or short forms, use `cannot' and `do not'
rather than `can't' or `don't'
To avoid having a number of different messages for the same
-situation, we'll use quoting like this `"message: `%s'"' for all
+situation, well will use quoting like this `"message: `%s'"' for all
strings. Numbers are not quoted:
-@verbatim
- _f ("cannot open file: `%s'", name_str)
- _f ("cannot find character number: %d", i)
-@end verbatim
-
+@example
+_f ("cannot open file: `%s'", name_str)
+_f ("cannot find character number: %d", i)
+@end example
+
@item
Think about translation issues. In a lot of cases, it is better to
-translate a whole message. The english grammar mustn't be imposed
+translate a whole message. The english grammar must not be imposed
on the translator. So, instead of
-@verbatim
- stem at + moment.str () + does not fit in beam
-@end verbatim
-
+@example
+stem at + moment.str () + does not fit in beam
+@end example
+
have
-@verbatim
- _f ("stem at %s does not fit in beam", moment.str ())
-@end verbatim
-
+@example
+_f ("stem at %s does not fit in beam", moment.str ())
+@end example
+
@item
Split up multi-sentence messages, whenever possible. Instead of
-@verbatim
- warning (_f ("out of tune! Can't find: `%s'",
-"Key_engraver"));
- warning (_f ("cannot find font `%s', loading default",
- font_name));
-@end verbatim
-
+@example
+warning (_f ("out of tune! Can't find: `%s'", "Key_engraver"));
+warning (_f ("cannot find font `%s', loading default", font_name));
+@end example
+
rather say:
-@verbatim
- warning (out of tune:;
- warning (_f ("cannot find: `%s', "Key_engraver"));
- warning (_f ("cannot find font: `%s', font_name));
- warning (_f ("Loading default font"));
-@end verbatim
-
+@example
+warning (_ ("out of tune:"));
+warning (_f ("cannot find: `%s', "Key_engraver"));
+warning (_f ("cannot find font: `%s', font_name));
+warning (_f ("Loading default font"));
+@end example
+
@item
If you must have multiple-sentence messages, use full punctuation.
Use two spaces after end of sentence punctuation. No punctuation
(esp. period) is used at the end of simple messages.
-@verbatim
- _f ("Non-matching braces in text `%s', adding braces", text)
- Debug output disabled. Compiled with NPRINT.
- _f ("Huh? Not a Request: `%s'. Ignoring.", request)
-@end verbatim
-
+@example
+_f ("Non-matching braces in text `%s', adding braces", text)
+_ ("Debug output disabled. Compiled with NPRINT.")
+_f ("Huh? Not a Request: `%s'. Ignoring.", request)
+@end example
+
@item
Do not modularise too much; words frequently cannot be translated
-without context. It's probably safe to treat most occurences of
+without context. It is probably safe to treat most occurences of
words like stem, beam, crescendo as separately translatable words.
@item
would mean sacrificing a bit of eloquency. This holds for original
messages too, of course.
-@verbatim
- en: cannot open: `foo.ly'
- + nl: kan `foo.ly' niet openen (1)
- kan niet openen: `foo.ly'* (2)
- niet te openen: `foo.ly'* (3)
-@end verbatim
+@example
+en: cannot open: `foo.ly'
++ nl: kan `foo.ly' niet openen (1)
+kan niet openen: `foo.ly'* (2)
+niet te openen: `foo.ly'* (3)
+@end example
+
-
The first nl message, although grammatically and stylistically
correct, is not friendly for parsing by humans (even if they speak
-dutch). I guess we'd prefer something like (2) or (3).
+dutch). I guess we would prefer something like (2) or (3).
@item
Do not run make po/po-update with GNU gettext < 0.10.35
Using a debugger simplifies troubleshooting in at least two ways.
First, breakpoints can be set to pause execution at any desired point.
-Then, when execution has paused, debugger commands can be issued to
+Then, when execution has paused, debugger commands can be issued to
explore the values of various variables or to execute functions.
Second, the debugger allows the display of a stack trace, which shows
@subsection Typical .gdbinit files
The behavior of gdb can be readily customized through the use of
-.gdbinit files. The file below is from Han-Wen. It sets breakpoints
+@var{.gdbinit} files. A @var{.gdbinit} file is a file named
+@var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
+ that is placed in a user's home directory.
+
+The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
for all errors and defines functions for displaying scheme objects
(ps), grobs (pgrob), and parsed music expressions (pmusic).
@example
-file lily/out/lilypond
-b scm_error
-b programming_error
-b Grob::programming_error
-
-define ps
- print ly_display_scm($arg0)
- end
- define pgrob
- print ly_display_scm($arg0->self_scm_)
- print ly_display_scm($arg0->mutable_property_alist_)
- print ly_display_scm($arg0->immutable_property_alist_)
- print ly_display_scm($arg0->object_alist_)
- end
- define pmusic
- print ly_display_scm($arg0->self_scm_)
- print ly_display_scm($arg0->mutable_property_alist_)
- print ly_display_scm($arg0->immutable_property_alist_)
- end
+file lily/out/lilypond
+b scm_error
+b programming_error
+b Grob::programming_error
+
+define ps
+ print ly_display_scm($arg0)
+ end
+ define pgrob
+ print ly_display_scm($arg0->self_scm_)
+ print ly_display_scm($arg0->mutable_property_alist_)
+ print ly_display_scm($arg0->immutable_property_alist_)
+ print ly_display_scm($arg0->object_alist_)
+ end
+ define pmusic
+ print ly_display_scm($arg0->self_scm_)
+ print ly_display_scm($arg0->mutable_property_alist_)
+ print ly_display_scm($arg0->immutable_property_alist_)
+ end
+@end example
+
+@subsection Using Guile interactively with LilyPond
+
+In order to experiment with Scheme programming in the LilyPond
+environment, it is convenient to have a Guile interpreter that
+has all the LilyPond modules loaded. This requires the following
+steps.
+First, define a Scheme symbol for the active module
+in the .ly file:
+
+@example
+#(module-define! (resolve-module '(guile-user))
+ 'lilypond-module (current-module))
@end example
+
+Second, place a Scheme function in the .ly file that gives an interactive Guile
+prompt:
+
+@example
+#(top-repl)
+@end example
+
+When the .ly file is compiled, this causes the compilation to be interrupted
+and an interactive guile prompt to appear. When the guile prompt appears,
+the LilyPond active module must be set as the current guile module:
+
+@example
+guile> (set-current-module lilypond-module)
+@end example
+
+Proper operation of these commands can be demonstrated by typing the name
+of a LilyPond public scheme function to see if it's properly defined:
+
+@example
+guile> fret-diagram-verbose-markup
+#<procedure fret-diagram-verbose-markup (layout props marking-list)>
+@end example
+
+If the LilyPond module has not been correctly loaded, an error
+message will be generated:
+
+@example
+guile> fret-diagram-verbose-markup
+ERROR: Unbound variable: fret-diagram-verbose-markup
+ABORT: (unbound-variable)
+@end example
+
+Once the module is properly loaded, any valid LilyPond Scheme expression
+can be entered at the interactive prompt.
+
+After the investigation is complete, the interactive guile interpreter
+can be exited:
+
+@example
+guile> (quit)
+@end example
+
+The compilation of the .ly file will then continue.
+
* Development phases::
* Minor release checklist::
* Major release checklist::
+* Making a release::
@end menu
+@node Making a release
+@section Making a release
+
+@itemize
+
+@item
+Build with GUB, and check the regtests.
+
+@item
+Upload the tarballs and sh scripts.
+
+@item
+(if major)
+Branch MASTER to stable/2.x.
+
+@item
+Make announcement.
+
+@end itemize
+
@node Introduction to website work
@section Introduction to website work
-
+Short answer: don't do it yet. We're completely revamping the
+website.
@node Translating the website
projects / lilypond.git / commitdiff