<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>GNU LilyPond program usage</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="GNU LilyPond program usage">
<meta name="generator" content="makeinfo 4.11">
<link title="Top" rel="top" href="#Top">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
hr { border:0; height:1; color: #000000; background-color: #000000; }
/* hr {
border: none;
height: 1px;
color: #666666;
background-color: #666666;
}
body {
border-left: 1px solid #666666;
border-right: 1px solid #666666;
color: #332d28;
margin-right: auto;
margin-left: auto;
width: 60em;
list-style-type: square;
font-family: Arial,Helvetica,sans-serif;
padding-right: 1em;
padding-left: 1em;
}
a {
border-bottom: 1px dashed #344242;
text-decoration: none;
color: #344242;
}
a:link {
text-decoration: none;
}
a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
a:active {
border-bottom: 1px solid #00cccc;
color: #00cccc;
}
a:hover {
border-bottom: 1px solid #1d7b85;
color: #1d7b85;
}
blockquote {
border: 1px solid #cccccc;
padding: 3px;
width: 40em;
}
.node {
border-left: 1px solid #666666;
margin: -0.5em 0px 1em;
padding: 2px 1px 0px;
font-style: italic;
}
.node a {
border: none;
text-decoration: underline;
font-style: normal;
font-weight: bold;
}
.verbatim {
font-family: "Courier New",Courier,monospace;
}
.unnumberedsubsubsec {
font-size: large;
color: #1d7b85;
}
.subsubheading {
font-size: large;
color: #3b220d;
}
.contents {
border: 1px dashed #339999;
margin: 3px 2em;
list-style-type: square;
padding-right: 1em;
width: 40em;
background-color: #fcfff9;
}
.contents a {
border-bottom: 1px dashed #423d34;
text-decoration: none;
color: #423d34;
}
.contents a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
.contents a:active {
border-bottom: 1px solid #f0d86d;
color: #f0d86d;
}
.contents a:hover {
border-bottom: 1px solid #3b220d;
color: #3b220d;
}
.menu {
border-left: 1px dashed #339999;
margin: 3px 2em 1em;
list-style-type: square;
padding-left: 1.4em;
width: 40em;
}
.unnumbered {
}
h2 {
font-size: x-large;
color: #1d7b85;
}
*/
--></style>
</head>
<BODY BGCOLOR=WHITE TEXT=BLACK>
This document is also available as a
<a href="../../Documentation/user/lilypond-program.pdf">PDF</a> and as
<a href="../../Documentation/user/lilypond-program-big-page.html">one big page</a>.
<!-- This produces the unified index -->
<p>This file documents GNU LilyPond program usage.
<p>Copyright 1999–2007 by the authors
<blockquote>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections.
A copy of the license is included in the section entitled “GNU
Free Documentation License”.
</blockquote>
<p><a name="Top"></a>
<h2 class="unnumbered">GNU LilyPond — program usage</h2>
<!-- HJJ: Info needs `@top', which is a synonym for `@unnumbered' in TeX. -->
<p>This is the Application Usage (AU) manual for GNU LilyPond version 2.11.57.
For more information about how this fits with the other
documentation, see <a name="index-About-the-documentation-1"></a><a href="lilypond-learning-big-page.html#About-the-documentation">About the documentation</a>.
<p><a name="index-web-site-2"></a><a name="index-URL-3"></a>
More information can be found at
<a href="http://www.lilypond.org/">http://www.lilypond.org/</a>. The website contains on-line copies
of this and other documentation.
<div class="contents">
<h2>Table of Contents</h2>
<ul>
<li><a name="toc_Top" href="#Top">GNU LilyPond — program usage</a>
<li><a name="toc_Install" href="#Install">1 Install</a>
<ul>
<li><a href="#Precompiled-binaries">1.1 Precompiled binaries</a>
<ul>
<li><a href="#Precompiled-binaries">Downloading</a>
</li></ul>
<li><a href="#Compiling-from-source">1.2 Compiling from source</a>
<ul>
<li><a href="#Downloading-source-code">1.2.1 Downloading source code</a>
<li><a href="#Requirements">1.2.2 Requirements</a>
<ul>
<li><a href="#Requirements">Compilation</a>
<li><a href="#Requirements">Running requirements</a>
<li><a href="#Requirements">Requirements for building documentation</a>
</li></ul>
<li><a href="#Building-LilyPond">1.2.3 Building LilyPond</a>
<ul>
<li><a href="#Building-LilyPond">Compiling</a>
<li><a href="#Building-LilyPond">Compiling for multiple platforms</a>
<li><a href="#Building-LilyPond">Compiling outside the source tree</a>
</li></ul>
<li><a href="#Building-documentation">1.2.4 Building documentation</a>
<ul>
<li><a href="#Commands-for-building-documentation">Commands for building documentation</a>
<li><a href="#Building-documentation-without-compiling-LilyPond">Building documentation without compiling LilyPond</a>
</li></ul>
<li><a href="#Testing-LilyPond">1.2.5 Testing LilyPond</a>
<li><a href="#Problems">1.2.6 Problems</a>
<ul>
<li><a href="#Problems">Bison 1.875</a>
<li><a href="#Problems">Solaris</a>
<li><a href="#Problems">FreeBSD</a>
<li><a href="#Problems">International fonts</a>
</li></ul>
</li></ul>
</li></ul>
<li><a name="toc_Setup" href="#Setup">2 Setup</a>
<ul>
<li><a href="#Setup-for-specific-Operating-Systems">2.1 Setup for specific Operating Systems</a>
<ul>
<li><a href="#MacOS-X-on-the-command_002dline">2.1.1 MacOS X on the command-line</a>
</li></ul>
<li><a href="#Text-editor-support">2.2 Text editor support</a>
<ul>
<li><a href="#Emacs-mode">2.2.1 Emacs mode</a>
<li><a href="#Vim-mode">2.2.2 Vim mode</a>
<li><a href="#jEdit">2.2.3 jEdit</a>
<li><a href="#TexShop">2.2.4 TexShop</a>
<li><a href="#TextMate">2.2.5 TextMate</a>
<li><a href="#LilyKDE">2.2.6 LilyKDE</a>
</li></ul>
<li><a href="#Point-and-click">2.3 Point and click</a>
</li></ul>
<li><a name="toc_Running-LilyPond" href="#Running-LilyPond">3 Running LilyPond</a>
<ul>
<li><a href="#Normal-usage">3.1 Normal usage</a>
<li><a href="#Command_002dline-usage">3.2 Command-line usage</a>
<ul>
<li><a href="#Invoking-lilypond">3.2.1 Invoking lilypond</a>
<li><a href="#Command-line-options">3.2.2 Command line options</a>
<li><a href="#Environment-variables">3.2.3 Environment variables</a>
</li></ul>
<li><a href="#Error-messages">3.3 Error messages</a>
<li><a href="#Updating-files-with-convert_002dly">3.4 Updating with <samp><span class="command">convert-ly</span></samp></a>
<ul>
<li><a href="#Updating-files-with-convert_002dly">3.4.1 Command line options</a>
<li><a href="#Problems-with-convert_002dly">3.4.2 Problems with <code>convert-ly</code></a>
</li></ul>
<li><a href="#Reporting-bugs">3.5 Reporting bugs</a>
</li></ul>
<li><a name="toc_LilyPond_002dbook" href="#LilyPond_002dbook">4 <samp><span class="command">lilypond-book</span></samp>: Integrating text and music</a>
<ul>
<li><a href="#An-example-of-a-musicological-document">4.1 An example of a musicological document</a>
<li><a href="#Integrating-music-and-text">4.2 Integrating music and text</a>
<ul>
<li><a href="#LaTeX">4.2.1 LaTeX</a>
<li><a href="#Texinfo">4.2.2 Texinfo</a>
<li><a href="#HTML">4.2.3 HTML</a>
<li><a href="#DocBook">4.2.4 DocBook</a>
</li></ul>
<li><a href="#Music-fragment-options">4.3 Music fragment options</a>
<li><a href="#Invoking-lilypond_002dbook">4.4 Invoking <samp><span class="command">lilypond-book</span></samp></a>
<li><a href="#Filename-extensions">4.5 Filename extensions</a>
<li><a href="#Alternate-methods-of-mixing-text-and-music">4.6 Alternative methods of mixing text and music</a>
<ul>
<li><a href="#Many-quotes-from-a-large-score">Many quotes from a large score</a>
<li><a href="#Inserting-LilyPond-output-into-OpenOffice_002eorg">Inserting LilyPond output into OpenOffice.org</a>
<li><a href="#Inserting-LilyPond-output-into-other-programs">Inserting LilyPond output into other programs</a>
</li></ul>
</li></ul>
<li><a name="toc_Converting-from-other-formats" href="#Converting-from-other-formats">5 Converting from other formats</a>
<ul>
<li><a href="#Invoking-midi2ly">5.1 Invoking <samp><span class="command">midi2ly</span></samp></a>
<li><a href="#Invoking-musicxml2ly">5.2 Invoking <code>musicxml2ly</code></a>
<li><a href="#Invoking-abc2ly">5.3 Invoking <code>abc2ly</code></a>
<li><a href="#Invoking-etf2ly">5.4 Invoking <samp><span class="command">etf2ly</span></samp></a>
<li><a href="#Generating-LilyPond-files">5.5 Generating LilyPond files</a>
</li></ul>
<li><a name="toc_GNU-Free-Documentation-License" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a>
<li><a name="toc_LilyPond-index" href="#LilyPond-index">Appendix B LilyPond index</a>
</li></ul>
</div>
<!-- *- coding: utf-8; mode: texinfo; -*- -->
<!-- This file is part of lilypond-program.tely -->
<!-- \version "2.11.51" -->
<p><a name="Install"></a>
<h2 class="chapter">1 Install</h2>
<!-- I don't know what this comment does. Remove? -gp -->
<p>There are two sets of releases for LilyPond: stable releases, and
unstable development releases. Stable versions have an even-numbered
‘minor’ version number (i.e. 2.8, 2.10, 2.12, etc). Development
versions have an odd-numbered ‘minor’ version number (i.e. 2.7, 2.9,
2.11, etc).
<p>Building LilyPond is a very involved process, so we <strong>highly</strong>
recommend using the precompiled binaries.
<p><a name="Precompiled-binaries"></a>
<h3 class="section">1.1 Precompiled binaries</h3>
<h4 class="unnumberedsubsec">Downloading</h4>
<p>Check out <a href="http://lilypond.org/web/install/">http://lilypond.org/web/install/</a> for up to date
information on binary packages for your platform. If your operating
system is not covered on that general page, please see the complete list
at <a href="http://download.linuxaudio.org/lilypond/binaries/">http://download.linuxaudio.org/lilypond/binaries/</a>
<p>We currently create binaries for
<pre class="example"> darwin-ppc - MacOS X powerpc
darwin-x86 - MacOS X intel
freebsd-64 - FreeBSD 6.x, x86_64
freebsd-x86 - FreeBSD 4.x, x86
linux-64 - Any GNU/Linux distribution, x86_64
linux-arm - Any GNU/Linux distribution, arm
linux-ppc - Any GNU/Linux distribution, powerpc
linux-x86 - Any GNU/Linux distribution, x86
mingw - Windows x86
</pre>
<!-- TRANSLATORS: -->
<!-- Please **do not** translate anything below this line. Users -->
<!-- should not be compiling LilyPond themselves; if they really -->
<!-- want to do so, they should be able to read the English docs, -->
<!-- because they'll probably need to ask questions in English -->
<!-- on the -devel list. -gp -->
<p><a name="Compiling-from-source"></a>
<h3 class="section">1.2 Compiling from source</h3>
<p><a name="Downloading-source-code"></a>
<h4 class="subsection">1.2.1 Downloading source code</h4>
<p>Download source
<ul>
<li>tarballs from
<a href="http://lilypond.org/download/">http://lilypond.org/download/</a> by HTTP.
<li>tarballs from
<a href="http://download.linuxaudio.org/lilypond/">http://download.linuxaudio.org/lilypond/</a> by HTTP.
<li>GIT from <a href="http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary">git.sv.gnu.org</a>
<pre class="example"> git clone git://git.sv.gnu.org/lilypond.git
</pre>
<p>The repository does not contain generated files. To create
<samp><span class="file">configure</span></samp>, run
<pre class="example"> ./autogen.sh
</pre>
</ul>
<p>For information on packaging, see <a href="http://lilypond.org/devel">http://lilypond.org/devel</a>.
<p><a name="Requirements"></a>
<h4 class="subsection">1.2.2 Requirements</h4>
<h5 class="unnumberedsubsubsec">Compilation</h5>
<p>In addition to the packages needed for running LilyPond (see below), you
need the following extra packages for building.
<p>When installing a binary package FOO, you may need to install the
FOO-devel, libFOO-dev or FOO-dev package too.
<ul>
<li><a href="http://fontforge.sf.net/">FontForge</a> 20060125 or newer.
<li>MetaFont (mf-nowin, mf, mfw or mfont binaries), usually packaged with
a LaTeX distribution like tetex or texlive.
<li><a href="http://www.lcdf.org/~eddietwo/type/#t1utils">t1utils</a>
(version 1.33 or newer recommended).
<li>New Century Schoolbook fonts, as PFB files. These are shipped with
X11 and Ghostscript, and are named <samp><span class="file">c059033l.pfb</span></samp>
<samp><span class="file">c059036l.pfb</span></samp>, <samp><span class="file">c059013l.pfb</span></samp> and <samp><span class="file">c059016l.pfb</span></samp>.
<li><a href="http://www.gnu.org/software/guile/guile.html">GUILE</a> (version
1.8.2 or newer). If you are installing binary packages, you may need to
install guile-devel or guile-dev or libguile-dev too.
<li><a href="ftp://ftp.gnu.org/gnu/texinfo/">Texinfo</a> (version 4.11 or newer).
<li><a href="http://gcc.gnu.org/">The GNU c++ compiler</a> (version 3.4 or
newer. 4.x is strongly recommended).
<li><a href="http://www.python.org">Python</a> (version 2.4 or newer)
<li><a href="ftp://ftp.gnu.org/gnu/make/">GNU Make</a> (version 3.78 or newer).
<li><a href="http://www.gnu.org/software/gettext/gettext.html">gettext</a>.
<li><a href="http://www.gnu.org/software/flex/">Flex</a>.
<li><a href="http://www.perl.org/">Perl</a>.
<li><a href="http://www.gnu.org/software/flex/">GNU Bison</a>.
<li>All packages required for running, including development packages with
header files and libraries.
</ul>
<h5 class="unnumberedsubsubsec">Running requirements</h5>
<p>Running LilyPond requires proper installation of the following software
<ul>
<li><a href="http://www.freetype.org/">Freetype</a> (version 2.1.10 or newer).
<li><a href="http://www.freetype.org/">FontConfig</a> (version 2.2).
<li><a href="http://www.pango.org/">Pango</a> (version 1.12 or newer).
<li><a href="http://www.gnu.org/software/guile/guile.html">GUILE</a>
(version 1.8.2 or newer), or patch 1.8.1 with
<a href="http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch">http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch</a>.
<li><a href="http://www.python.org">Python</a> (version 2.4 or newer).
<li><a href="http://www.ghostscript.com">Ghostscript</a> (version 8.15 or
newer. 8.50 recommended)
<li>Dejaview. (This is normally installed by default)
</ul>
<p>International fonts are required to create music with international text
or lyrics.
<h5 class="unnumberedsubsubsec">Requirements for building documentation</h5>
<p>You can view the documentation online at
<a href="http://lilypond.org/doc/">http://lilypond.org/doc/</a>, but you can also build it locally.
This process requires a successful compile of LilyPond, and some
additional tools and packages
<ul>
<li>The <a href="http://netpbm.sourceforge.net/">netpbm utilities</a>
<li>ImageMagick
<li>International fonts (see input/regression/utf-8.ly for hints
about which font packages are necessary for your platform)
<li>Ghostscript, 8.50 with the patch from
<a href="http://bugs.ghostscript.com/show_bug.cgi?id=688154">http://bugs.ghostscript.com/show_bug.cgi?id=688154</a>
and the patch from
<a href="http://bugs.ghostscript.com/show_bug.cgi?id=688017">http://bugs.ghostscript.com/show_bug.cgi?id=688017</a>, or use
a release of Ghostscript which includes these patches, for example
8.60 or newer.
</ul>
<p><a name="Building-LilyPond"></a>
<h4 class="subsection">1.2.3 Building LilyPond</h4>
<h5 class="unnumberedsubsubsec">Compiling</h5>
<p>To install GNU LilyPond, type
<pre class="example"> gunzip -c lilypond-x.y.z | tar xf -
cd lilypond-x.y.z
./configure # run with --help for applicable options
make
su -c 'make install'
</pre>
<p class="noindent">If you are not root, you should choose a <code>--prefix</code> argument that
points into your home directory, e.g.
<pre class="example"> ./configure --prefix=$HOME/usr
</pre>
<h5 class="unnumberedsubsubsec">Compiling for multiple platforms</h5>
<p>If you want to build multiple versions of LilyPond with different
configuration settings, you can use the <code>--enable-config=CONF</code>
option of <samp><span class="command">configure</span></samp>. You should use <code>make conf=CONF</code>
to generate the output in <samp><span class="file">out-CONF</span></samp>. For example, suppose you
want to build with and without profiling, then use the following for
the normal build
<pre class="example"> ./configure --prefix=$HOME/usr/ --enable-checking
make
make install
</pre>
<p>and for the profiling version, specify a different configuration
<pre class="example"> ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
make conf=prof
make conf=prof install
</pre>
<h5 class="unnumberedsubsubsec">Compiling outside the source tree</h5>
<p>It is possible to compile LilyPond in a build tree different from the
source tree, with <code>--srcdir</code> option of <samp><span class="command">configure</span></samp>:
<pre class="example"> mkdir lily-build && cd lily-build
<var>sourcedir</var>/configure --srcdir=<var>sourcedir</var>
</pre>
<p><a name="Building-documentation"></a>
<h4 class="subsection">1.2.4 Building documentation</h4>
<p>This requires a successful compile of LilyPond, or using an external
LilyPond binary.
<p><a name="Commands-for-building-documentation"></a>
<h5 class="unnumberedsubsubsec">Commands for building documentation</h5>
<p>The documentation is built by issuing
<pre class="example"> make web
</pre>
<p>After compilation, the HTML documentation tree is available in
<samp><span class="file">out-www/offline-root/</span></samp>, and can be browsed locally.
<p>The HTML and PDF files can be installed into the standard documentation
path by issuing
<pre class="example"> make web-install
</pre>
<p class="noindent">This also installs Info documentation with images if the installation
prefix is properly set; otherwise, instructions for manual installation
of Info documentation are printed on standard output.
<p>It is also possible to build a documentation tree in
<samp><span class="file">out-www/online-root/</span></samp>, with special processing, so it can be used
on a website with content negotiation for automatic language selection;
this can be achieved by issuing
<pre class="example"> make WEB_TARGETS=online web
</pre>
<p class="noindent">and both ‘offline’ and ‘online’ targets can be generated by issuing
<pre class="example"> make WEB_TARGETS="offline online" web
</pre>
<p>Several targets are available to clean the documentation build and
help with maintaining documentation; an overview of these targets is
available with
<pre class="example"> make help
</pre>
<p class="noindent">from every directory in the build tree. Most targets for
documentation maintenance are available from <samp><span class="file">Documentation/</span></samp>;
for more information, see <samp><span class="file">Documentation/user/README.txt</span></samp> and
<samp><span class="file">Documentation/TRANSLATION</span></samp>.
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p><code>-j</code> command-line option of <samp><span class="command">make</span></samp> is unsupported for
building the documentation. As the most time consuming task is
running LilyPond to build images of music, the makefile variable
<code>CPU_COUNT</code> may be set in <samp><span class="file">local.make</span></samp> or on the command line
to the number of <code>.ly</code> files that LilyPond should process
simultaneously, e.g. on a bi-processor or Dual core machine
<pre class="example"> make CPU_COUNT=2 web
</pre>
<p>If source files have changed since last documentation build, output
files that need to be rebuilt are normally rebuilt, even if you do not
run <code>make web-clean</code> first. However, building dependencies in the
documentation are so complex that rebuilding of some targets may not
be triggered as they should be; a workaround is to force rebuilding
by touching appropriate files, e.g.
<pre class="example"> touch Documentation/user/*.itely
touch input/lsr/*.ly
</pre>
<p><a name="Building-documentation-without-compiling-LilyPond"></a>
<h5 class="unnumberedsubsubsec">Building documentation without compiling LilyPond</h5>
<p>The documentation can be built locally without compiling LilyPond
binary, if LilyPond is already installed on your system.
<p>From a fresh Git checkout, do
<pre class="example"> ./autogen.sh # ignore any warning messages
cp GNUmakefile.in GNUmakefile
make -C python
nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
</pre>
<p>Please note that this may break sometimes – for example, if a new
feature is added with a test file in input/regression, even the latest
development release of LilyPond will fail to build the docs.
<p>You may build the manual without building all the <samp><span class="file">input/*</span></samp>
stuff: change directory, for example to <samp><span class="file">Documentation/user</span></samp>,
issue <code>make web</code>, which will build documentation in a
subdirectory <samp><span class="file">out-www</span></samp> from the source files in current
directory. In this case, if you also want to browse the documentation
in its post-processed form, change back to top directory and issue
<pre class="example"> make out=www WWW-post
</pre>
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p>You may also need to create a script for <samp><span class="command">pngtopnm</span></samp> and
<code>pnmtopng</code>. On GNU/Linux, I use this:
<pre class="verbatim">
export LD_LIBRARY_PATH=/usr/lib
exec /usr/bin/pngtopnm "$@"
</pre>
<p>On MacOS X, I use this:
<pre class="verbatim">
export DYLD_LIBRARY_PATH=/sw/lib
exec /sw/bin/pngtopnm "$@"
</pre>
<p><a name="Testing-LilyPond"></a>
<h4 class="subsection">1.2.5 Testing LilyPond</h4>
<p><a name="testing"></a>
<p>LilyPond comes with an extensive suite that exercises the entire
program. This suite can be used to automatically check the impact of a
change. This is done as follows
<pre class="example"> make test-baseline
<em>## apply your changes, compile</em>
make check
</pre>
<p>This will leave an HTML page <samp><span class="file">out/test-results/index.html</span></samp>. This
page shows all the important differences that your change introduced,
whether in the layout, MIDI, performance or error reporting.
<p>To rerun tests, use
<pre class="example"> make test-redo <em>## redo files differing from baseline</em>
make test-clean <em>## remove all test results</em>
</pre>
<p class="noindent">and then run <code>make check</code> again.
<p>For tracking memory usage as part of this test, you will need GUILE
CVS; especially the following patch:
<a href="http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch">http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch</a>.
<p>For checking the coverage of the test suite, do the following
<pre class="example"> ./buildscripts/build-coverage.sh
<em># uncovered files, least covered first</em>
python ./buildscripts/coverage.py --summary out-cov/*.cc
<em># consecutive uncovered lines, longest first</em>
python ./buildscripts/coverage.py --uncovered out-cov/*.cc
</pre>
<p><a name="Problems"></a>
<h4 class="subsection">1.2.6 Problems</h4>
<p>For help and questions use <a href="mailto:lilypond-user@gnu.org">lilypond-user@gnu.org</a>. Send bug
reports to <a href="mailto:bug-lilypond@gnu.org">bug-lilypond@gnu.org</a>.
<p>Bugs that are not fault of LilyPond are documented here.
<h5 class="unnumberedsubsubsec">Bison 1.875</h5>
<p>There is a bug in bison-1.875: compilation fails with "parse error
before `goto'" in line 4922 due to a bug in bison. To fix, please
recompile bison 1.875 with the following fix
<pre class="example"> $ cd lily; make out/parser.cc
$ vi +4919 out/parser.cc
# append a semicolon to the line containing "__attribute__ ((__unused__))
# save
$ make
</pre>
<h5 class="unnumberedsubsubsec">Solaris</h5>
<p>Solaris7, ./configure
<p><samp><span class="file">./configure</span></samp> needs a POSIX compliant shell. On Solaris7,
<samp><span class="file">/bin/sh</span></samp> is not yet POSIX compliant, but <samp><span class="file">/bin/ksh</span></samp> or bash
is. Run configure like
<pre class="example"> CONFIG_SHELL=/bin/ksh ksh -c ./configure
</pre>
<p class="noindent">or
<pre class="example"> CONFIG_SHELL=/bin/bash bash -c ./configure
</pre>
<h5 class="unnumberedsubsubsec">FreeBSD</h5>
<p>To use system fonts, dejaview must be installed. With the default
port, the fonts are installed in <samp><span class="file">usr/X11R6/lib/X11/fonts/dejavu</span></samp>.
<p>Open the file <samp><span class="file">$LILYPONDBASE/usr/etc/fonts/local.conf</span></samp> and add the
following line just after the <code><fontconfig></code> line. (Adjust as necessary
for your hierarchy.)
<pre class="example"> <dir>/usr/X11R6/lib/X11/fonts</dir>
</pre>
<h5 class="unnumberedsubsubsec">International fonts</h5>
<p>On MacOS X, all fonts are installed by default. However, finding all
system fonts requires a bit of configuration; see
<a href="http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html">this post</a> on the <code>lilypond-user</code> mailing list.
<p>On Linux, international fonts are installed by different means on
every distribution. We cannot list the exact commands or packages
that are necessary, as each distribution is different, and the exact
package names within each distribution changes. Here are some
hints, though:
<pre class="verbatim">
Red Hat Fedora
taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
ttfonts-zh_CN fonts-ja fonts-hebrew
Debian GNU/Linux
apt-get install emacs-intl-fonts xfonts-intl-.* \
ttf-kochi-gothic ttf-kochi-mincho \
xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
</pre>
<!-- *- coding: utf-8; mode: texinfo; -*- -->
<!-- This file is part of lilypond-program.tely -->
<!-- \version "2.11.51" -->
<p><a name="Setup"></a>
<h2 class="chapter">2 Setup</h2>
<p>This chapter discusses various post-install configuration options for
LilyPond and various other programs. This chapter may be safely treated
as a reference: only read a section if it applies to you.
<p><a name="Setup-for-specific-Operating-Systems"></a>
<h3 class="section">2.1 Setup for specific Operating Systems</h3>
<p>This section explains how to perform additional setup for specific
operating systems.
<p><a name="MacOS-X-on-the-command-line"></a>
<a name="MacOS-X-on-the-command_002dline"></a>
<h4 class="subsection">2.1.1 MacOS X on the command-line</h4>
<p>The scripts (such as lilypond-book, convert-ly, abc2ly, and even
lilypond itself) are included inside the .app file for MacOS X. They can be run from
the command line by invoking them directly, e.g.
<pre class="example"> <var>path/to</var>/LilyPond.app/Contents/Resources/bin/lilypond
</pre>
<p class="noindent">The same is true of the other scripts in that directory, including
lilypond-book, convert-ly, abc2ly, etc.
<p>Alternatively, you may create scripts which add the path
automatically. Create a directory to store these scripts,
<pre class="example"> mkdir -p ~/bin
cd ~/bin
</pre>
<p>Create a file called <code>lilypond</code> which contains
<pre class="example"> exec <var>path/to</var>/LilyPond.app/Contents/Resources/bin/lilypond "$@"
</pre>
<p>Create similar files <code>lilypond-book</code>, <code>convert-ly</code>, and
any other helper programs you use (<code>abc2ly</code>, <code>midi2ly</code>,
etc). Simply replace the <code>bin/lilypond</code> with
<code>bin/convert-ly</code> (or other program name) in the above file.
<p>Make the file executable,
<pre class="example"> chmod u+x lilypond
</pre>
<p>Now, add this directory to your path. Modify (or create)
a file called <code>.profile</code> in your home directory such that it contains
<pre class="example"> export PATH=$PATH:~/bin
</pre>
<p class="noindent">This file should end with a blank line.
<p>Note that <var>path/to</var> will generally be <code>/Applications/</code>.
<p><a name="Text-editor-support"></a>
<h3 class="section">2.2 Text editor support</h3>
<p><a name="index-editors-4"></a><a name="index-vim-5"></a><a name="index-emacs-6"></a><a name="index-modes_002c-editor-7"></a><a name="index-syntax-coloring-8"></a><a name="index-coloring_002c-syntax-9"></a>
There is support from different text editors for LilyPond.
<p><a name="Emacs-mode"></a>
<h4 class="subsection">2.2.1 Emacs mode</h4>
<p>Emacs has a <samp><span class="file">lilypond-mode</span></samp>, which provides keyword
autocompletion, indentation, LilyPond specific parenthesis matching
and syntax coloring, handy compile short-cuts and reading LilyPond
manuals using Info. If <samp><span class="file">lilypond-mode</span></samp> is not installed on your
platform, see below.
<p>An Emacs mode for entering music and running LilyPond is contained in
the source archive in the <samp><span class="file">elisp</span></samp> directory. Do <samp><span class="command">make
install</span></samp> to install it to <var>elispdir</var>. The file <samp><span class="file">lilypond-init.el</span></samp>
should be placed to <var>load-path</var><samp><span class="file">/site-start.d/</span></samp> or appended
to your <samp><span class="file">~/.emacs</span></samp> or <samp><span class="file">~/.emacs.el</span></samp>.
<p>As a user, you may want add your source path (e.g. <samp><span class="file">~/site-lisp/</span></samp>) to
your <var>load-path</var> by appending the following line (as modified) to your
<samp><span class="file">~/.emacs</span></samp>
<!-- any reason we do not advise: (push "~/site-lisp" load-path) -->
<pre class="example"> (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
</pre>
<p><a name="Vim-mode"></a>
<h4 class="subsection">2.2.2 Vim mode</h4>
<p>For <a href="http://www.vim.org">VIM</a>, a <samp><span class="file">vimrc</span></samp> is supplied,
along with syntax coloring tools. A Vim mode for entering music and
running LilyPond is contained in the source archive in <code>$VIM</code>
directory.
<p>The LilyPond file type is detected if the file
<samp><span class="file">~/.vim/filetype.vim</span></samp> has the following content
<pre class="example"> if exists("did_load_filetypes")
finish
endif
augroup filetypedetect
au! BufNewFile,BufRead *.ly setf lilypond
augroup END
</pre>
<p>Please include this path by appending the following line to your
<samp><span class="file">~/.vimrc</span></samp>
<pre class="example"> set runtimepath+=/usr/local/share/lilypond/${LILYPOND_VERSION}/vim/
</pre>
<p class="noindent">where ${LILYPOND_VERSION} is your LilyPond version. If LilyPond was not
installed in <samp><span class="file">/usr/local/</span></samp>, then change this path accordingly.
<p><a name="jEdit"></a>
<h4 class="subsection">2.2.3 jEdit</h4>
<p>Created as a plugin for the <a href="http://www.jedit.org">jEdit</a>
text editor, LilyPondTool is the most feature-rich text-based tool for
editing LilyPond scores. Its features include a Document Wizard with
lyrics support to set up documents easier, and embedded PDF viewer with
advanced point-and-click support. For screenshots, demos and
installation instructions, visit
<a href="http://lilypondtool.organum.hu">http://lilypondtool.organum.hu</a>
<p><a name="TexShop"></a>
<h4 class="subsection">2.2.4 TexShop</h4>
<p>The <a href="http://www.uoregon.edu/~koch/texshop/index.html">TexShop</a>
editor for MacOS X can be extended to run LilyPond, lilypond-book and
convert-ly from within the editor, using the extensions available at
<a href="http://www.dimi.uniud.it/vitacolo/freesoftware.html">http://www.dimi.uniud.it/vitacolo/freesoftware.html</a>.
<p><a name="TextMate"></a>
<h4 class="subsection">2.2.5 TextMate</h4>
<p>There is a LilyPond bundle for TextMate. It may be installed by running
<pre class="example"> mkdir -p /Library/Application\ Support/TextMate/Bundles
cd /Library/Application\ Support/TextMate/Bundles
svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/
</pre>
<p><a name="LilyKDE"></a>
<h4 class="subsection">2.2.6 LilyKDE</h4>
<p><a href="http://lilykde.googlecode.com/">LilyKDE</a> is a plugin for KDE's
text editor <a href="http://kate-editor.org/">Kate</a>. It has a powerful Score
Wizard to quickly setup a LilyPond document and an embedded PDF viewer.
<p>LilyKDE can use <a href="http://www.volny.cz/smilauer/rumor/">Rumor</a>,
so music can entered by playing on a MIDI keyboard.
<p>Other features are lyric hyphenation and running LilyPond on multiple files
at once from within the KDE file manager.
<p><a name="Point-and-click"></a>
<h3 class="section">2.3 Point and click</h3>
<p><a name="index-point-and-click-10"></a>
<p>Point and click lets you find notes in the input by clicking on them
in the PDF viewer. This makes it easier to find input that causes
some error in the sheet music.
<p>When this functionality is active, LilyPond adds hyperlinks to the PDF
file. These hyperlinks are sent to the web-browser, which opens a
text-editor with the cursor in the right place.
<p>To make this chain work, you should configure your PDF viewer to
follow hyperlinks using the <samp><span class="file">lilypond-invoke-editor</span></samp> script
supplied with LilyPond.
<p>For Xpdf on UNIX, the following should be present in
<samp><span class="file">xpdfrc</span></samp><a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>
<pre class="example"> urlCommand "lilypond-invoke-editor %s"
</pre>
<p>The program <samp><span class="file">lilypond-invoke-editor</span></samp> is a small helper
program. It will invoke an editor for the special <code>textedit</code>
URIs, and run a web browser for others. It tests the environment
variable <code>EDITOR</code> for the following patterns,
<dl>
<dt><code>emacs</code><dd> this will invoke
<pre class="example"> emacsclient --no-wait +<var>line</var>:<var>column</var> <var>file</var>
</pre>
<br><dt><code>vim</code><dd> this will invoke
<pre class="example"> gvim --remote +:<var>line</var>:norm<var>char</var> <var>file</var>
</pre>
<br><dt><code>nedit</code><dd>this will invoke
<pre class="example"> nc -noask +<var>line</var> <var>file</var>'
</pre>
</dl>
<p>The environment variable <code>LYEDITOR</code> is used to override this. It
contains the command line to start the editor, where <code>%(file)s</code>,
<code>%(column)s</code>, <code>%(line)s</code> is replaced with the file, column
and line respectively. The setting
<pre class="example"> emacsclient --no-wait +%(line)s:%(column)s %(file)s
</pre>
<p class="noindent">for <code>LYEDITOR</code> is equivalent to the standard emacsclient
invocation.
<p><a name="index-file-size_002c-output-11"></a>
The point and click links enlarge the output files significantly. For
reducing the size of PDF and PS files, point and click may be switched
off by issuing
<pre class="example"> \pointAndClickOff
</pre>
<p class="noindent">in a <samp><span class="file">.ly</span></samp> file. Point and click may be explicitly enabled with
<pre class="example"> \pointAndClickOn
</pre>
<p>Alternately, you may disable point and click with a command-line
option:
<pre class="example"> lilypond -dno-point-and-click file.ly
</pre>
<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
<b>Note:</b> You should always turn off point and click in any LilyPond
files to be distributed to avoid including path information about
your computer in the .pdf file, which can pose a security risk.
</td></tr></table>
<!-- *- coding: utf-8; mode: texinfo; -*- -->
<!-- This file is part of lilypond-program.tely -->
<!-- \version "2.11.57" -->
<p><a name="Running-LilyPond"></a>
<h2 class="chapter">3 Running LilyPond</h2>
<p>This chapter details the technicalities of running LilyPond.
<p><a name="Normal-usage"></a>
<h3 class="section">3.1 Normal usage</h3>
<p>Most users run LilyPond through a GUI; see <a name="index-First-steps-12"></a><a href="lilypond-learning-big-page.html#First-steps">First steps</a> if
you have not read this already.
<p><a name="Command-line-usage"></a>
<a name="Command_002dline-usage"></a>
<h3 class="section">3.2 Command-line usage</h3>
<p>This section contains extra information about using LilyPond on the
command-line. This may be desirable to pass extra options to the
program. In addition, there are certain extra ‘helper’ programs (such
as <code>midi2ly</code>) which are only available on the command-line.
<p>By ‘command-line’, we mean the command line in the operating system.
Windows users might be more familiar with the terms ‘DOS shell’ or
‘command shell’; MacOS X users might be more familiar with the terms
‘terminal’ or ‘console’. They should also consult <a href="#MacOS-X-on-the-command_002dline">MacOS X on the command-line</a>.
<p>Describing how to use this part of an operating system is outside the
scope of this manual; please consult other documentation on this topic
if you are unfamiliar with the command-line.
<p><a name="Invoking-lilypond"></a>
<h4 class="subsection">3.2.1 Invoking lilypond</h4>
<p><a name="index-Invoking-LilyPond-13"></a><a name="index-command-line-options-14"></a><a name="index-options_002c-command-line-15"></a><a name="index-switches-16"></a>
<p>The <samp><span class="command">lilypond</span></samp> executable may be called as follows from the command line.
<pre class="example"> lilypond [<var>option</var>]... <var>file</var>...
</pre>
<p>When invoked with a filename that has no extension, the <samp><span class="file">.ly</span></samp>
extension is tried first. To read input from stdin, use a
dash (<code>-</code>) for <var>file</var>.
<p>When <samp><span class="file">filename.ly</span></samp> is processed it will produce <samp><span class="file">filename.ps</span></samp>
and <samp><span class="file">filename.pdf</span></samp> as output. Several files can be specified;
they will each be processed independently. <a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a>
<p>If <samp><span class="file">filename.ly</span></samp> contains more than one <code>\score</code>
block, then the rest of the scores will be output in numbered files,
starting with <samp><span class="file">filename-1.pdf</span></samp>. In addition, the value of
<code>output-suffix</code> will be inserted between the basename and the
number. An input file containing
<pre class="example"> #(define output-suffix "violin")
\book { ... }
#(define output-suffix "cello")
\book { ... }
</pre>
<p class="noindent">will output <var>base</var><samp><span class="file">-violin.pdf</span></samp> and
<var>base</var><samp><span class="file">-cello-1.pdf</span></samp>.
<p><a name="Command-line-options"></a>
<h4 class="subsection">3.2.2 Command line options</h4>
<p>The following options are supported:
<dl>
<dt><code>-e,--evaluate=</code><var>expr</var><dd>Evaluate the Scheme <var>expr</var> before parsing any <samp><span class="file">.ly</span></samp> files.
Multiple <code>-e</code> options may be given, they will be evaluated
sequentially.
<p>The expression will be evaluated in the <code>guile-user</code> module, so
if you want to use definitions in <var>expr</var>, use
<pre class="example"> lilypond -e '(define-public a 42)'
</pre>
<p class="noindent">on the command-line, and include
<pre class="example"> #(use-modules (guile-user))
</pre>
<p class="noindent">at the top of the <code>.ly</code> file.
<br><dt><code>-f,--format=</code><var>format</var><dd>which formats should be written. Choices for <code>format</code> are
<code>svg</code>, <code>ps</code>, <code>pdf</code>, <code>png</code>, <code>tex</code>, <code>dvi</code>.
<p>Example: <code>lilypond -fpng filename.ly</code>
<br><dt><code>-d,--define-default=</code><var>var</var><code>=</code><var>val</var><dd>This sets the internal program option <var>var</var> to the Scheme value
<var>val</var>. If <var>val</var> is not supplied, then <var>#t</var> is used. To
switch off an option, <code>no-</code> may be prefixed to <var>var</var>, e.g.
<p><a name="index-point-and-click_002c-command-line-17"></a>
<pre class="example"> -dno-point-and-click
</pre>
<p class="noindent">is the same as
<pre class="example"> -dpoint-and-click='#f'
</pre>
<p>Here are a few interesting options.
<dl>
<dt>‘<samp><span class="samp">help</span></samp>’<dd>Running <code>lilypond -dhelp</code> will print all of the <code>-d</code> options
available.
<br><dt>‘<samp><span class="samp">paper-size</span></samp>’<dd>This option sets the default paper-size,
<pre class="example"> -dpaper-size=\"letter\"
</pre>
<p class="noindent">Note that the string must be enclosed in escaped quotes ( <code>\"</code> ).
<br><dt>‘<samp><span class="samp">safe</span></samp>’<dd>Do not trust the <code>.ly</code> input.
<p>When LilyPond formatting is available through a web server, either the
<code>--safe</code> or the <code>--jail</code> option <b>MUST</b> be passed. The
<code>--safe</code> option will prevent inline Scheme code from wreaking
havoc, for example
<blockquote>
<pre class="verbatim">
#(system "rm -rf /")
{
c4^#(ly:export (ly:gulp-file "/etc/passwd"))
}
</pre>
</blockquote>
<p>The <code>-dsafe</code> option works by evaluating in-line Scheme
expressions in a special safe module. This safe module is derived from
GUILE <samp><span class="file">safe-r5rs</span></samp> module, but adds a number of functions of the
LilyPond API. These functions are listed in <samp><span class="file">scm/safe-lily.scm</span></samp>.
<p>In addition, safe mode disallows <code>\include</code> directives and
disables the use of backslashes in TeX strings.
<p>In safe mode, it is not possible to import LilyPond variables
into Scheme.
<p>safe does <em>not</em> detect resource overuse. It is still possible to
make the program hang indefinitely, for example by feeding cyclic data
structures into the backend. Therefore, if using LilyPond on a
publicly accessible webserver, the process should be limited in both
CPU and memory usage.
<p>The safe mode will prevent many useful LilyPond snippets from being
compiled. The <code>--jail</code> is a more secure alternative, but
requires more work to set up.
<br><dt>‘<samp><span class="samp">backend</span></samp>’<dd>the output format to use for the back-end. Choices for <code>format</code> are
<dl>
<dt><code>tex</code><dd>for TeX output, to be processed with LaTeX. If present, the file
<samp><span class="file">file.textmetrics</span></samp> is read to determine text extents.
<br><dt><code>texstr</code><dd>dump text strings to <samp><span class="file">.texstr</span></samp> file, which can be run through
(La)TeX, resulting in a <code>.textmetrics</code> file, which contains the
extents of strings of text. <strong>Warning:</strong> this functionality is
currently missing due to heavy restructuring of the source code.
<br><dt><code>ps</code><dd> for PostScript.
<a name="index-PostScript-output-18"></a>
Postscript files include TTF, Type1 and OTF fonts. No subsetting of
these fonts is done. When using oriental character sets, this can
lead to huge files.
<br><dt><code>eps</code><dd> for encapsulated PostScript. This dumps every page (system) as a separate
<samp><span class="file">EPS</span></samp> file, without fonts, and as one collated <samp><span class="file">EPS</span></samp> file with
all pages (systems) including fonts.
<p>This mode is used by default by lilypond-book.
<br><dt><code>svg</code><dd> for SVG (Scalable Vector Graphics). This dumps every page as a separate
<samp><span class="file">SVG</span></samp> file, with embedded fonts.
<a name="index-SVG-_0028Scalable-Vector-Graphics_0029-19"></a> You need a SVG viewer which supports embedded fonts, or a SVG
viewer which is able to replace the embedded fonts with OTF fonts.
Under UNIX, you may use <a href="http://www.inkscape.org">Inkscape</a>
(version 0.42 or later), after copying the OTF fonts in directory
<samp><span class="file">PATH/TO/share/lilypond/VERSION/fonts/otf/</span></samp> to <samp><span class="file">~/.fonts/</span></samp>.
<br><dt><code>scm</code><dd> for a dump of the raw, internal Scheme-based drawing commands.
<a name="index-Scheme-dump-20"></a></dl>
<p>Example: <code>lilypond -dbackend=svg filename.ly</code>
<p><a name="index-output-format_002c-setting-21"></a>
<br><dt>‘<samp><span class="samp">preview</span></samp>’<dd>Generate an output file containing the titles and the first system
<br><dt>‘<samp><span class="samp">print-pages</span></samp>’<dd>Generate the full pages, the default. <code>-dno-print-pages</code> is
useful in combination with <code>-dpreview</code>.
</dl>
<br><dt><code>-h,--help</code><dd>Show a summary of usage.
<br><dt><code>-H,--header=FIELD</code><dd>Dump a header field to file BASENAME.FIELD
<br><dt><code>--include, -I=</code><var>directory</var><dd>Add <var>directory</var> to the search path for input files.
<a name="index-file-searching-22"></a><a name="index-search-path-23"></a>
<br><dt><code>-i,--init=</code><var>file</var><dd>Set init file to <var>file</var> (default: <samp><span class="file">init.ly</span></samp>).
<br><dt><code>-o,--output=</code><var>FILE</var><dd>Set the default output file to <var>FILE</var>. The appropriate
suffix will be added (ie <code>.pdf</code> for pdf, <code>.tex</code>
for tex, etc).
<br><dt><code>--ps</code><dd>Generate PostScript.
<br><dt><code>--dvi</code><dd>Generate DVI files. In this case, the TeX backend should be
specified, i.e., <code>-dbackend=tex</code>.
<br><dt><code>--png</code><dd>Generate pictures of each page, in PNG format. This implies
<code>--ps</code>. The resolution in DPI of the image may be set with
<pre class="example"> -dresolution=110
</pre>
<br><dt><code>--pdf</code><dd>Generate PDF. This implies <code>--ps</code>.
<br><dt><code>-j,--jail=</code><var>user</var><code>,</code><var>group</var><code>,</code><var>jail</var><code>,</code><var>dir</var><dd>Run <samp><span class="command">lilypond</span></samp> in a chroot jail.
<p>The <code>--jail</code> option provides a more flexible alternative to
<code>--safe</code> when LilyPond formatting is available through a web
server or whenever LilyPond executes externally provided
sources.
<p>The <code>--jail</code> option works by changing the root of <samp><span class="command">lilypond</span></samp> to
<var>jail</var> just before starting the actual compilation process. The user
and group are then changed to match those provided, and the current
directory is changed to <var>dir</var>. This setup guarantees that it is not
possible (at least in theory) to escape from the jail. Note that for
<code>--jail</code> to work <samp><span class="command">lilypond</span></samp> must be run as root, which is usually
accomplished in a safe way using <samp><span class="command">sudo</span></samp>.
<p>Setting up a jail is a slightly delicate matter, as we must be sure that
LilyPond is able to find whatever it needs to compile the source
<em>inside the jail</em>. A typical setup comprises the following items:
<dl>
<dt>Setting up a separate filesystem<dd>A separate filesystem should be created for LilyPond, so that it can be
mounted with safe options such as <code>noexec</code>, <code>nodev</code>, and
<code>nosuid</code>. In this way, it is impossible to run executables or to
write directly to a device from LilyPond. If you do not want to create a
separate partition, just create a file of reasonable size and use it to
mount a loop device. A separate filesystem also guarantees that LilyPond
cannot write more space than it is allowed.
<br><dt>Setting up a separate user<dd>A separate user and group (say, <code>lily</code>/<code>lily</code>) with low
privileges should be used to run LilyPond inside the jail. There should
be a single directory writable by this user, which should be passed in
<var>dir</var>.
<br><dt>Preparing the jail<dd>LilyPond needs to read a number of files while running. All these files
are to be copied into the jail, under the same path they appear in the
real root filesystem. The entire content of the LilyPond installation
(e.g., <samp><span class="file">/usr/share/lilypond</span></samp>)
should be copied.
<p>If problems arise, the simplest way to trace them down is to run
LilyPond using <samp><span class="command">strace</span></samp>, which will allow you to determine which
files are missing.
<br><dt>Running LilyPond<dd>In a jail mounted with <code>noexec</code> it is impossible to execute any external
program. Therefore LilyPond must be run with a backend that does not
require any such program. As we already mentioned, it must be also run
with superuser privileges (which, of course, it will lose immediately),
possibly using <samp><span class="command">sudo</span></samp>. It is a good idea to limit the number of
seconds of CPU time LilyPond can use (e.g., using <samp><span class="command">ulimit
-t</span></samp>), and, if your operating system supports it, the amount of memory
that can be allocated.
</dl>
<br><dt><code>-v,--version</code><dd>Show version information.
<br><dt><code>-V,--verbose</code><dd>Be verbose: show full paths of all files read, and give timing
information.
<br><dt><code>-w,--warranty</code><dd>Show the warranty with which GNU LilyPond comes. (It comes with
<strong>NO WARRANTY</strong>!)
</dl>
<p><a name="Environment-variables"></a>
<h4 class="subsection">3.2.3 Environment variables</h4>
<p><a name="index-LANG-24"></a><a name="index-LILYPOND_005fDATADIR-25"></a>
<samp><span class="command">lilypond</span></samp> recognizes the following environment variables:
<dl>
<dt><code>LILYPOND_DATADIR</code><dd>This specifies a directory where locale messages and
data files will be looked up by default. The directory should contain
subdirectories called <samp><span class="file">ly/</span></samp>, <samp><span class="file">ps/</span></samp>, <samp><span class="file">tex/</span></samp>, etc.
<br><dt><code>LANG</code><dd>This selects the language for the warning messages.
<br><dt><code>LILYPOND_GC_YIELD</code><dd>With this variable the memory footprint and performance can be
adjusted. It is a percentage tunes memory management behavior. With
higher values, the program uses more memory, with smaller values, it
uses more CPU time. The default value is <code>70</code>.
</dl>
<p><a name="Error-messages"></a>
<h3 class="section">3.3 Error messages</h3>
<p><a name="index-error-messages-26"></a>Different error messages can appear while compiling a file:
<dl>
<dt><em>Warning</em><dd><a name="index-warning-27"></a>Something looks suspect. If you are requesting something out of the
ordinary then you will understand the message, and can ignore it.
However, warnings usually indicate that something is wrong with the
input file.
<br><dt><em>Error</em><dd>Something is definitely wrong. The current processing step (parsing,
interpreting, or formatting) will be finished, but the next step will
be skipped.
<br><dt><em>Fatal error</em><dd><a name="index-error-28"></a><a name="index-fatal-error-29"></a>Something is definitely wrong, and LilyPond cannot continue. This
happens rarely. The most usual cause is misinstalled fonts.
<br><dt><em>Scheme error</em><dd><a name="index-trace_002c-Scheme-30"></a><a name="index-call-trace-31"></a><a name="index-Scheme-error-32"></a>Errors that occur while executing Scheme code are caught by the Scheme
interpreter. If running with the verbose option (<code>-V</code> or
<code>--verbose</code>) then a call trace of the offending
function call is printed.
<br><dt><em>Programming error</em><dd><a name="index-Programming-error-33"></a>There was some internal inconsistency. These error messages are
intended to help the programmers and debuggers. Usually, they can be
ignored. Sometimes, they come in such big quantities that they obscure
other output.
<br><dt><em>Aborted (core dumped)</em><dd>This signals a serious programming error that caused the program to
crash. Such errors are considered critical. If you stumble on one,
send a bug-report.
</dl>
<p><a name="index-errors_002c-message-format-34"></a>If warnings and errors can
be linked to some part of the input file, then error messages have the
following form
<pre class="example"> <var>filename</var>:<var>lineno</var>:<var>columnno</var>: <var>message</var>
<var>offending input line</var>
</pre>
<p>A line-break is inserted in the offending line to indicate the column
where the error was found. For example,
<pre class="example"> test.ly:2:19: error: not a duration: 5
{ c'4 e'
5 g' }
</pre>
<p>These locations are LilyPond's best guess about where the warning or
error occurred, but (by their very nature) warnings and errors occur
when something unexpected happens. If you can't see an error in the
indicated line of your input file, try checking one or two lines
above the indicated position.
<p><a name="Updating-files-with-convert-ly"></a>
<a name="Updating-files-with-convert_002dly"></a>
<h3 class="section">3.4 Updating with <samp><span class="command">convert-ly</span></samp></h3>
<p><a name="index-Updating-a-LilyPond-file-35"></a><a name="index-convert_002dly-36"></a>
The LilyPond input syntax is routinely changed to simplify it or improve
it in different ways. As a side effect of this, the LilyPond interpreter
often is no longer compatible with older input files. To remedy this,
the program <samp><span class="command">convert-ly</span></samp> can be used to deal with most of the
syntax changes between LilyPond versions.
<p>It uses <code>\version</code> statements in the input files to detect the
old version number. In most cases, to upgrade your input file it is
sufficient to run
<pre class="example"> convert-ly -e myfile.ly
</pre>
<p class="noindent">MacOS X users may execute this command under the menu entry
<code>Compile > Update syntax</code>.
<p>If there are no changes to myfile.ly and file called myfile.ly.NEW
is created, then myfile.ly is already updated.
<h4 class="subsection">3.4.1 Command line options</h4>
<p><samp><span class="command">convert-ly</span></samp> always converts up to the last syntax change handled by
it. This means that the <code>\version</code> number left in the file is
usually lower than the version of <samp><span class="command">convert-ly</span></samp> itself.
<p>To upgrade LilyPond fragments in texinfo files, use
<pre class="example"> convert-ly --from=... --to=... --no-version *.itely
</pre>
<p>To see the changes in the LilyPond syntax between two versions, use
<pre class="example"> convert-ly --from=... --to=... -s
</pre>
<p>To upgrade many files at once, combine <code>convert-ly</code> with
standard UNIX commands. This example will upgrade all <code>.ly</code>
files in the current directory
<pre class="example"> for f in *.ly; do convert-ly -e $f; done;
</pre>
<p>In general, the program is invoked as follows:
<pre class="example"> convert-ly [<var>option</var>]... <var>file</var>...
</pre>
<p>The following options can be given:
<dl>
<dt><code>-e,--edit</code><dd>Do an inline edit of the input file. Overrides <code>--output</code>.
<br><dt><code>-f,--from=</code><var>from-patchlevel</var><dd>Set the version to convert from. If this is not set, <samp><span class="command">convert-ly</span></samp>
will guess this, on the basis of <code>\version</code> strings in the file.
<br><dt><code>-n,--no-version</code><dd>Normally, <samp><span class="command">convert-ly</span></samp> adds a <code>\version</code> indicator
to the output. Specifying this option suppresses this.
<br><dt><code>-s, --show-rules</code><dd>Show all known conversions and exit.
<br><dt><code>--to=</code><var>to-patchlevel</var><dd>Set the goal version of the conversion. It defaults to the latest
available version.
<br><dt><code>-h, --help</code><dd>Print usage help.
</dl>
<p><a name="Problems-with-convert-ly"></a>
<a name="Problems-with-convert_002dly"></a>
<h4 class="subsection">3.4.2 Problems with <code>convert-ly</code></h4>
<p>Not all language changes are handled. Only one output option can be
specified. Automatically updating scheme and LilyPond scheme
interfaces is quite unlikely; be prepared to tweak scheme code
manually.
<pre class="verbatim">
There are a few things that the convert-ly cannot handle. Here's a list
of limitations that the community has complained about.
This bug report structure has been chosen because convert-ly has a
structure that doesn't allow to smoothly implement all needed changes.
Thus this is just a wishlist, placed here for reference.
1.6->2.0:
Doesn't always convert figured bass correctly, specifically things like {<
>}. Mats' comment on working around this:
To be able to run convert-ly
on it, I first replaced all occurrences of '{<' to some dummy like '{#'
and similarly I replaced '>}' with '&}'. After the conversion, I could
then change back from '{ #' to '{ <' and from '& }' to '> }'.
Doesn't convert all text markup correctly. In the old markup syntax,
it was possible to group a number of markup commands together within
parentheses, e.g.
-#'((bold italic) "string")
This will incorrectly be converted into
-\markup{{\bold italic} "string"}
instead of the correct
-\markup{\bold \italic "string"}
2.0->2.2:
Doesn't handle \partcombine
Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
stanzas.
2.0->2.4:
\magnify isn't changed to \fontsize.
- \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
remove-tag isn't changed.
- \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
first-page-number isn't changed.
- first-page-number no => print-first-page-number = ##f
Line breaks in header strings aren't converted.
- \\\\ as line break in \header strings => \markup \center-align <
"First Line" "Second Line" >
Crescendo and decrescendo terminators aren't converted.
- \rced => \!
- \rc => \!
2.2->2.4:
\turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
converted.
2.4.2->2.5.9
\markup{ \center-align <{ ... }> } should be converted to:
\markup{ \center-align {\line { ... }} }
but now, \line is missing.
2.4->2.6
Special LaTeX characters such as $~$ in text are not converted to UTF8.
2.8
\score{} must now begin with a music expression. Anything else
(particularly \header{}) must come after the music.
</pre>
<p><a name="Reporting-bugs"></a>
<h3 class="section">3.5 Reporting bugs</h3>
<p><a name="index-bugs-37"></a><a name="index-reporting-bugs-38"></a>
If you have input that results in a crash or an erroneous output, then
that is a bug. There is a list of current bugs on our Google bug tracker,
<p><a href="http://code.google.com/p/lilypond/issues/list">http://code.google.com/p/lilypond/issues/list</a>
<p>If you have discovered a bug which is not listed, please report the
bug by following the directions on
<p><a href="http://lilypond.org/web/devel/participating/bugs">http://lilypond.org/web/devel/participating/bugs</a>
<p>Please construct and submit minimal examples of bugs in reports. We do not
have the resources to investigate reports which are not as small as possible.
<!-- *- coding: utf-8; mode: texinfo; -*- -->
<!-- This file is part of lilypond-program.tely -->
<!-- \version "2.11.51" -->
<!-- Note: keep this node named so that `info lilypond-book' brings you here. -->
<p><a name="LilyPond-book"></a>
<a name="LilyPond_002dbook"></a>
<h2 class="chapter">4 <samp><span class="command">lilypond-book</span></samp>: Integrating text and music</h2>
<p>If you want to add pictures of music to a document, you can simply do it
the way you would do with other types of pictures. The pictures are
created separately, yielding PostScript output or PNG images, and those
are included into a LaTeX or HTML document.
<p><samp><span class="command">lilypond-book</span></samp> provides a way to automate this process: This
program extracts snippets of music from your document, runs
<samp><span class="command">lilypond</span></samp> on them, and outputs the document with pictures
substituted for the music. The line width and font size definitions for
the music are adjusted to match the layout of your document.
<p>This is a separate program from <samp><span class="command">lilypond</span></samp> itself, and is run on
the command-line; for more information, see <a href="#Command_002dline-usage">Command-line usage</a>.
<p>This procedure may be applied to LaTeX, HTML, Texinfo or DocBook documents.
<p><a name="index-texinfo-39"></a><a name="index-latex-40"></a><a name="index-texinfo-41"></a><a name="index-texi-42"></a><a name="index-html-43"></a><a name="index-docbook-44"></a><a name="index-documents_002c-adding-music-to-45"></a><a name="index-HTML_002c-music-in-46"></a><a name="index-Texinfo_002c-music-in-47"></a><a name="index-DocBook_002c-music-in-48"></a><a name="index-g_t_0040LaTeX_007b_007d_002c-music-in-49"></a>
<p><a name="An-example-of-a-musicological-document"></a>
<h3 class="section">4.1 An example of a musicological document</h3>
<p><a name="index-musicology-50"></a>Some texts contain music examples. These texts are musicological
treatises, songbooks, or manuals like this. Such texts can be made by
hand, simply by importing a PostScript figure into the word processor.
However, there is an automated procedure to reduce the amount of work
involved in HTML, LaTeX, Texinfo and DocBook documents.
<p>A script called <code>lilypond-book</code> will extract the music fragments,
format them, and put back the resulting notation. Here we show a small
example for use with LaTeX. The example also contains explanatory
text, so we will not comment on it further.
<h4 class="subheading">Input</h4>
<blockquote>
<pre class="verbatim">
\documentclass[a4paper]{article}
\begin{document}
Documents for \verb+lilypond-book+ may freely mix music and text.
For example,
\begin{lilypond}
\relative c' {
c2 g'2 \times 2/3 { f8 e d } c'2 g4
}
\end{lilypond}
Options are put in brackets.
\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
c'4 f16
\end{lilypond}
Larger examples can be put into a separate file, and introduced with
\verb+\lilypondfile+.
\lilypondfile[quote,noindent]{screech-boink.ly}
(If needed, replace screech-boink.ly by any .ly file you put in the same
directory as this file.)
\end{document}
</pre>
</blockquote>
<h4 class="subheading">Processing</h4>
<p>Save the code above to a file called <samp><span class="file">lilybook.lytex</span></samp>, then in a
terminal run
<!-- keep space after @version{} so TeX doesn't choke -->
<pre class="example"> lilypond-book --output=out --pdf lilybook.lytex
<em>lilypond-book (GNU LilyPond) 2.11.57 </em>
<em>Reading lilybook.lytex...</em>
<em>..lots of stuff deleted..</em>
<em>Compiling lilybook.tex...</em>
cd out
pdflatex lilybook
<em>..lots of stuff deleted..</em>
xpdf lilybook
<em>(replace </em><samp><span class="command">xpdf</span></samp><em> by your favorite PDF viewer)</em>
</pre>
<p>Running <samp><span class="command">lilypond-book</span></samp> and <samp><span class="command">latex</span></samp> creates a lot of
temporary files, which would clutter up the working directory. To
remedy this, use the <code>--output=</code><var>dir</var> option. It will create
the files in a separate subdirectory <samp><span class="file">dir</span></samp>.
<p>Finally the result of the LaTeX example shown above.<a rel="footnote" href="#fn-3" name="fnd-3"><sup>3</sup></a> This finishes the tutorial section.
<h4 class="subheading">Output</h4>
<p>Documents for <samp><span class="command">lilypond-book</span></samp> may freely mix music and text.
For example,
<p class="noindent"><p>
<a href="3e/lily-9bbaa8c4.ly">
<img align="middle"
border="0" src="3e/lily-9bbaa8c4.png" alt="[image of music]">
</a>
</p>
<p>Options are put in brackets.
<blockquote>
<pre class="verbatim">
c'4 f16
</pre>
<p>
<a href="d9/lily-9f16f5f9.ly">
<img align="middle"
border="0" src="d9/lily-9f16f5f9.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>Larger examples can be put into a separate file, and introduced with
<code>\lilypondfile</code>.
<blockquote>
<p>
<a href="34/lily-278653e5.ly">
<img align="middle"
border="0" src="34/lily-278653e5.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p><a name="Integrating-music-and-text"></a>
<h3 class="section">4.2 Integrating music and text</h3>
<p>Here we explain how to integrate LilyPond with various output formats.
<p><a name="LaTeX"></a>
<h4 class="subsection">4.2.1 LaTeX</h4>
<p>LaTeX is the de-facto standard for publishing layouts in the exact
sciences. It is built on top of the TeX typesetting engine,
providing the best typography available anywhere.
<p>See
<a href="http://www.ctan.org/tex-archive/info/lshort/english/"><em>The Not So Short Introduction to LaTeX</em></a> for an overview on how
to use LaTeX.
<p>Music is entered using
<pre class="example">\begin[options,go,here]{lilypond}
YOUR LILYPOND CODE
\end{lilypond}
</pre>
<p class="noindent">or
<pre class="example">\lilypondfile[options,go,here]{<var>filename</var>}
</pre>
<p class="noindent">or
<pre class="example">\lilypond{ YOUR LILYPOND CODE }
</pre>
<p>Running <samp><span class="command">lilypond-book</span></samp> yields a file that can be further
processed with LaTeX.
<p>We show some examples here. The <code>lilypond</code> environment
<pre class="example">\begin[quote,fragment,staffsize=26]{lilypond}
c' d' e' f' g'2 g'2
\end{lilypond}
</pre>
<p class="noindent">produces
<blockquote>
<p>
<a href="d3/lily-b1f75a08.ly">
<img align="middle"
border="0" src="d3/lily-b1f75a08.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p>The short version
<pre class="example">\lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
</pre>
<p class="noindent">produces
<blockquote>
<p>
<a href="ac/lily-6d07893b.ly">
<img align="middle"
border="0" src="ac/lily-6d07893b.png" alt="[image of music]">
</a>
</p>
</blockquote>
<p class="noindent">Currently, you cannot include <code>{</code> or <code>}</code> within
<code>\lilypond{}</code>, so this command is only useful with the
<code>fragment</code> option.
<p>The default line width of the music will be adjusted by examining the
commands in the document preamble, the part of the document before
<code>\begin{document}</code>. The <samp><span class="command">lilypond-book</span></samp> command sends
these to LaTeX to find out how wide the text is. The line width for
the music fragments is then adjusted to the text width. Note that this
heuristic algorithm can fail easily; in such cases it is necessary to
use the <code>line-width</code> music fragment option.
<p><a name="index-titling-and-lilypond_002dbook-51"></a><a name="index-g_t_005cheader-in-_0040LaTeX_007b_007d-documents-52"></a>
Each snippet will call the following macros if they have been defined by
the user:
<ul>
<li><code>\preLilyPondExample</code> called before the music,
<li><code>\postLilyPondExample</code> called after the music,
<li><code>\betweenLilyPondSystem[1]</code> is called between systems if
<code>lilypond-book</code> has split the snippet into several PostScript
files. It must be defined as taking one parameter and will be
passed the number of files already included in this snippet.
The default is to simply insert a <code>\linebreak</code>.
</ul>
<p class="noindent">
<h5 class="subsubheading">Selected Snippets</h5>
<p>Sometimes it is useful to display music elements (such as ties and slurs)
as if they continued after the end of the fragment. This can be done by
breaking the staff and suppressing inclusion of the rest of the LilyPond
output.
<p>In LaTeX, define <code>\betweenLilyPondSystem</code> in such a way that
inclusion of other systems is terminated once the required number of
systems are included. Since <code>\betweenLilypondSystem</code> is first
called <em>after</em> the first system, including only the first system
is trivial.
<pre class="example">\def\betweenLilyPondSystem#1{\endinput}
\begin[fragment]{lilypond}
c'1\( e'( c'~ \break c' d) e f\)
\end{lilypond}
</pre>
<p>If a greater number of systems is requested, a TeX conditional must
be used before the <code>\endinput</code>. In this example, replace ‘2’ by
the number of systems you want in the output,
<pre class="example">\def\betweenLilyPondSystem#1{
\ifnum##1<2\else\endinput\fi
}
</pre>
<p>Remember that the definition of <code>\betweenLilyPondSystem</code> is
effective until TeX quits the current group (such as the LaTeX
environment) or is overridden by another definition (which is, in
most cases, for the rest of the document). To reset your
definition, write
<pre class="example">\let\betweenLilyPondSystem\undefined
</pre>
<p class="noindent">in your LaTeX source.
<p>This may be simplified by defining a TeX macro
<pre class="example">\def\onlyFirstNSystems#1{
\def\betweenLilyPondSystem##1{\ifnum##1<#1\else\endinput\fi}
}
</pre>
<p class="noindent">and then saying only how many systems you want before each fragment,
<pre class="example">\onlyFirstNSystems{3}
\begin{lilypond}...\end{lilypond}
\onlyFirstNSystems{1}
\begin{lilypond}...\end{lilypond}
</pre>
<p class="noindent">
<h5 class="subsubheading">See also</h5>
<p class="indent">
There are specific <samp><span class="command">lilypond-book</span></samp> command line options and
other details to know when processing LaTeX documents, see
<a href="#Invoking-lilypond_002dbook">Invoking lilypond-book</a>.
<p><a name="Texinfo"></a>
<h4 class="subsection">4.2.2 Texinfo</h4>
<p>Texinfo is the standard format for documentation of the GNU project. An
example of a Texinfo document is this manual. The HTML, PDF, and Info
versions of the manual are made from the Texinfo document.
<p>In the input file, music is specified with
<pre class="example">@lilypond[options,go,here]
YOUR LILYPOND CODE
@end lilypond
</pre>
<p class="noindent">or
<pre class="example">@lilypond[options,go,here]{ YOUR LILYPOND CODE }
</pre>
<p class="noindent">or
<pre class="example">@lilypondfile[options,go,here]{<var>filename</var>}
</pre>
<p>When <samp><span class="command">lilypond-book</span></samp> is run on it, this results in a Texinfo
file (with extension <samp><span class="file">.texi</span></samp>) containing <code>@image</code> tags for
HTML, Info and printed output. <samp><span class="command">lilypond-book</span></samp> generates images
of the music in EPS and PDF formats for use in the printed output, and
in PNG format for use in HTML and Info output.
<p>We show two simple examples here. A <code>lilypond</code> environment
<pre class="example">@lilypond[fragment]
c' d' e' f' g'2 g'
@end lilypond
</pre>
<p class="noindent">produces
<p class="noindent"><p>
<a href="28/lily-476ee964.ly">
<img align="middle"
border="0" src="28/lily-476ee964.png" alt="[image of music]">
</a>
</p>
<p>The short version
<pre class="example">@lilypond[fragment,staffsize=11]{<c' e' g'>}
</pre>
<p class="noindent">produces
<p class="noindent"><p>
<a href="c3/lily-3e6a6357.ly">
<img align="middle"
border="0" src="c3/lily-3e6a6357.png" alt="[image of music]">
</a>
</p>
<p>Contrary to LaTeX, <code>@lilypond{...}</code> does not generate an
in-line image. It always gets a paragraph of its own.
<p><a name="HTML"></a>
<h4 class="subsection">4.2.3 HTML</h4>
<p>Music is entered using
<pre class="example"><lilypond fragment relative=2>
\key c \minor c4 es g2
</lilypond>
</pre>
<p class="noindent"><samp><span class="command">lilypond-book</span></samp> then produces an HTML file with appropriate image
tags for the music fragments:
<p class="noindent"><p>
<a href="bb/lily-466262cd.ly">
<img align="middle"
border="0" src="bb/lily-466262cd.png" alt="[image of music]">
</a>
</p>
<p>For inline pictures, use <code><lilypond ... /></code>, where the options
are separated by a colon from the music, for example
<pre class="example">Some music in <lilypond relative=2: a b c/> a line of text.
</pre>
<p>To include separate files, say
<pre class="example"><lilypondfile <var>option1</var> <var>option2</var> ...><var>filename</var></lilypondfile>
</pre>
<p><a name="index-titling-in-HTML-53"></a><a name="index-preview-image-54"></a><a name="index-thumbnail-55"></a>
<a name="DocBook"></a>
<h4 class="subsection">4.2.4 DocBook</h4>
<p>For inserting LilyPond snippets it is good to keep the conformity of our
DocBook document, thus allowing us to use DocBook editors, validation
etc. So we don't use custom tags, only specify a convention based on the
standard DocBook elements.
<h4 class="subheading">Common conventions</h4>
<p>For inserting all type of snippets we use the <code>mediaobject</code> and
<code>inlinemediaobject</code> element, so our snippets can be formatted
inline or not inline. The snippet formatting options are always
provided in the <code>role</code> property of the innermost element (see in
next sections). Tags are chosen to allow DocBook editors format the
content gracefully. The DocBook files to be processed with
<samp><span class="command">lilypond-book</span></samp> should have the extension <samp><span class="file">.lyxml</span></samp>.
<h4 class="subheading">Including a LilyPond file</h4>
<p>This is the most simple case. We must use the <samp><span class="file">.ly</span></samp> extension for
the included file, and insert it as a standard <code>imageobject</code>, with
the following structure:
<pre class="example"><mediaobject>
<imageobject>
<imagedata fileref="music1.ly" role="printfilename" />
</imageobject>
</mediaobject>
</pre>
<p>Note that you can use <code>mediaobject</code> or <code>inlinemediaobject</code>
as the outermost element as you wish.
<h4 class="subheading">Including LilyPond code</h4>
<p>Including LilyPond code is possible by using a <code>programlisting</code>,
where the language is set to <code>lilypond</code> with the following
structure:
<pre class="example"><inlinemediaobject>
<textobject>
<programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
\context Staff \with {
\remove Time_signature_engraver
\remove Clef_engraver}
{ c4( fis) }
</programlisting>
</textobject>
</inlinemediaobject>
</pre>
<p>As you can see, the outermost element is a <code>mediaobject</code> or
<code>inlinemediaobject</code>, and there is a <code>textobject</code> containing
the <code>programlisting</code> inside.
<h4 class="subheading">Processing the DocBook document</h4>
<p>Running <samp><span class="command">lilypond-book</span></samp> on our <samp><span class="file">.lyxml</span></samp> file will create a
valid DocBook document to be further processed with <samp><span class="file">.xml</span></samp>
extension. If you use
<a href="http://dblatex.sourceforge.net">dblatex</a>, it will create a
PDF file from this document automatically. For HTML (HTML Help,
JavaHelp etc.) generation you can use the official DocBook XSL
stylesheets, however, it is possible that you have to make some
customization for it.
<p><a name="Music-fragment-options"></a>
<h3 class="section">4.3 Music fragment options</h3>
<p>In the following, a ‘LilyPond command’ refers to any command described
in the previous sections which is handled by <samp><span class="command">lilypond-book</span></samp> to
produce a music snippet. For simplicity, LilyPond commands are only
shown in LaTeX syntax.
<p>Note that the option string is parsed from left to right; if an option
occurs multiple times, the last one is taken.
<p>The following options are available for LilyPond commands:
<dl>
<dt><code>staffsize=</code><var>ht</var><dd>Set staff size to <var>ht</var>, which is measured in points.
<br><dt><code>ragged-right</code><dd>Produce ragged-right lines with natural spacing, i.e.,
<code>ragged-right = ##t</code> is added to the LilyPond snippet. This is the
default for the <code>\lilypond{}</code> command if no <code>line-width</code>
option is present. It is also the default for the <code>lilypond</code>
environment if the <code>fragment</code> option is set, and no line width is
explicitly specified.
<br><dt><code>noragged-right</code><dd>For single-line snippets, allow the staff length to be stretched to
equal that of the line width, i.e., <code>ragged-right = ##f</code> is
added to the LilyPond snippet.
<!-- does this option still exist in lilypond? -jm -->
<br><dt><code>packed</code><dd>Produce lines with packed spacing, i.e., <code>packed = ##t</code> is added
to the LilyPond snippet.
<br><dt><code>line-width</code><dt><code>line-width=</code><var>size</var><code>\</code><var>unit</var><dd>Set line width to <var>size</var>, using <var>unit</var> as units. <var>unit</var> is
one of the following strings: <code>cm</code>, <code>mm</code>, <code>in</code>, or
<code>pt</code>. This option affects LilyPond output (this is, the staff
length of the music snippet), not the text layout.
<p>If used without an argument, set line width to a default value (as
computed with a heuristic algorithm).
<p>If no <code>line-width</code> option is given, <samp><span class="command">lilypond-book</span></samp> tries to
guess a default for <code>lilypond</code> environments which don't use the
<code>ragged-right</code> option.
<br><dt><code>notime</code><dd>Do not print the time signature, and turns off the timing (key signature,
bar lines) in the score.
<br><dt><code>fragment</code><dd>Make <samp><span class="command">lilypond-book</span></samp> add some boilerplate code so that you can
simply enter, say,
<pre class="example"> c'4
</pre>
<p class="noindent">without <code>\layout</code>, <code>\score</code>, etc.
<br><dt><code>nofragment</code><dd>Do not add additional code to complete LilyPond code in music snippets.
Since this is the default, <code>nofragment</code> is redundant normally.
<br><dt><code>indent=</code><var>size</var><code>\</code><var>unit</var><dd>Set indentation of the first music system to <var>size</var>, using
<var>unit</var> as units. <var>unit</var> is one of the following strings:
<code>cm</code>, <code>mm</code>, <code>in</code>, or <code>pt</code>. This option affects
LilyPond, not the text layout.
<br><dt><code>noindent</code><dd>Set indentation of the first music system to zero. This option affects
LilyPond, not the text layout. Since no indentation is the default,
<code>noindent</code> is redundant normally.
<br><dt><code>quote</code><dd>Reduce line length of a music snippet by 2*0.4<span class="dmn">in</span> and put
the output into a quotation block. The value ‘0.4<span class="dmn">in</span>’ can be
controlled with the <code>exampleindent</code> option.
<br><dt><code>exampleindent</code><dd>Set the amount by which the <code>quote</code> option indents a music snippet.
<br><dt><code>relative</code><dt><code>relative=</code><var>n</var><dd>Use relative octave mode. By default, notes are specified relative to
middle C. The optional integer argument specifies the octave of
the starting note, where the default <code>1</code> is middle C.
<code>relative</code> option only works when <code>fragment</code> option is set,
so <code>fragment</code> is automatically implied by <code>relative</code>,
regardless of the presence of any <code>(no)fragment</code> option in the
source.
</dl>
<p>LilyPond also uses <samp><span class="command">lilypond-book</span></samp> to produce its own
documentation. To do that, some more obscure music fragment options are
available.
<dl>
<dt><code>verbatim</code><dd>The argument of a LilyPond command is copied to the output file and
enclosed in a verbatim block, followed by any text given with the
<code>intertext</code> option (not implemented yet); then the actual music is
displayed. This option does not work well with <code>\lilypond{}</code> if
it is part of a paragraph.
<p>If <code>verbatim</code> is used in a <code>lilypondfile</code> command, it is
possible to enclose verbatim only a part of the source file. If the
source file contain a comment containing ‘<samp><span class="samp">begin verbatim</span></samp>’ (without
quotes), quoting the source in the verbatim block will start after the
last occurrence of such a comment; similarly, quoting the source verbatim
will stop just before the first occurrence of a comment containing
‘<samp><span class="samp">end verbatim</span></samp>’, it there is any. In the following source file
example, the music will be interpreted in relative mode, but the
verbatim quote will not show the <code>relative</code> block, i.e.
<pre class="example"> \relative c' { % begin verbatim
c4 e2 g4
f2 e % end verbatim
}
</pre>
<p class="noindent">will be printed with a verbatim block like
<pre class="example"> c4 e2 g4
f2 e
</pre>
<br><dt><code>addversion</code><dd>(Only for Texinfo output.) Prepend line <code>\version
@w{"@version{}"}</code> to <code>verbatim</code> output.
<br><dt><code>texidoc</code><dd>(Only for Texinfo output.) If <samp><span class="command">lilypond</span></samp> is called with the
<samp><span class="option">--header=texidoc</span></samp> option, and the file to be processed is
called <samp><span class="file">foo.ly</span></samp>, it creates a file <samp><span class="file">foo.texidoc</span></samp> if there
is a <code>texidoc</code> field in the <code>\header</code>. The <code>texidoc</code>
option makes <samp><span class="command">lilypond-book</span></samp> include such files, adding its
contents as a documentation block right before the music snippet.
<p>Assuming the file <samp><span class="file">foo.ly</span></samp> contains
<pre class="example"> \header {
texidoc = "This file demonstrates a single note."
}
{ c'4 }
</pre>
<p class="noindent">and we have this in our Texinfo document <samp><span class="file">test.texinfo</span></samp>
<pre class="example"> @lilypondfile[texidoc]{foo.ly}
</pre>
<p class="noindent">the following command line gives the expected result
<pre class="example"> lilypond-book --process="lilypond --format=tex --tex \
--header=texidoc test.texinfo
</pre>
<p>Most LilyPond test documents (in the <samp><span class="file">input</span></samp> directory of the
distribution) are small <samp><span class="file">.ly</span></samp> files which look exactly like this.
<p>For localization purpose, if the Texinfo document contains
<code>@documentlanguage </code><var>LANG</var> and <samp><span class="file">foo.ly</span></samp> header
contains a <code>texidoc</code><var>LANG</var> field, and if <samp><span class="command">lilypond</span></samp>
is called with <samp><span class="option">--header=texidoc</span><var>LANG</var></samp>, then
<samp><span class="file">foo.texidoc</span><var>LANG</var></samp> will be included instead of
<samp><span class="file">foo.texidoc</span></samp>.
<br><dt><code>lilyquote</code><dd>(Only for Texinfo output.) This option is similar to quote, but only
the music snippet (and the optional verbatim block implied by
<code>verbatim</code> option) is put into a quotation block. This option is
useful if you want to <code>quote</code> the music snippet but not the
<code>texidoc</code> documentation block.
<br><dt><code>doctitle</code><dd>(Only for Texinfo output.) This option works similarly to
<code>texidoc</code> option: if <samp><span class="command">lilypond</span></samp> is called with the
<samp><span class="option">--header=doctitle</span></samp> option, and the file to be processed is
called <samp><span class="file">foo.ly</span></samp> and contains a <code>doctitle</code> field in the
<code>\header</code>, it creates a file <samp><span class="file">foo.doctitle</span></samp>. When
<code>doctitle</code> option is used, the contents of <samp><span class="file">foo.doctitle</span></samp>,
which should be a single line of <var>text</var>, is inserted in the
Texinfo document as <code>@lydoctitle </code><var>text</var>.
<code>@lydoctitle</code> should be a macro defined in the Texinfo document.
The same remark about <code>texidoc</code> processing with localized
languages also applies to <code>doctitle</code>.
<br><dt><code>printfilename</code><dd>If a LilyPond input file is included with <code>\lilypondfile</code>, print
the file name right before the music snippet. For HTML output, this
is a link. Only the base name of the file is printed, i.e. the
directory part of the file path is stripped.
<br><dt><code>fontload</code><dd>This option includes fonts in all of the generated EPS-files for this
snippet. This should be used if the snippet uses any font that LaTeX
cannot find on its own.
</dl>
<p><a name="Invoking-lilypond-book"></a>
<a name="Invoking-lilypond_002dbook"></a>
<h3 class="section">4.4 Invoking <samp><span class="command">lilypond-book</span></samp></h3>
<p><samp><span class="command">lilypond-book</span></samp> produces a file with one of the following
extensions: <samp><span class="file">.tex</span></samp>, <samp><span class="file">.texi</span></samp>, <samp><span class="file">.html</span></samp> or <samp><span class="file">.xml</span></samp>,
depending on the output format. All of <samp><span class="file">.tex</span></samp>, <samp><span class="file">.texi</span></samp> and
<samp><span class="file">.xml</span></samp> files need further processing.
<h4 class="subheading">Format-specific instructions</h4>
<h5 class="subsubheading">LaTeX</h5>
<p>There are two ways of processing your LaTeX document for printing or
publishing: getting a PDF file directly with PDFLaTeX, or getting a
PostScript file with LaTeX via a DVI to PostScript translator like
<samp><span class="command">dvips</span></samp>. The first way is simpler and recommended<a rel="footnote" href="#fn-4" name="fnd-4"><sup>4</sup></a>, and whichever
way you use, you can easily convert between PostScript and PDF with
tools, like <samp><span class="command">ps2pdf</span></samp> and <samp><span class="command">pdf2ps</span></samp> included in
Ghostscript package.
<p>To produce a PDF file through PDFLaTeX, use
<pre class="example">lilypond-book --pdf yourfile.pdftex
pdflatex yourfile.tex
</pre>
<p><a name="index-outline-fonts-56"></a><a name="index-type1-fonts-57"></a><a name="index-dvips-58"></a><a name="index-invoking-dvips-59"></a>To produce PDF output via LaTeX/<samp><span class="command">dvips</span></samp>/<samp><span class="command">ps2pdf</span></samp>, you
should do
<pre class="example">lilypond-book yourfile.lytex
latex yourfile.tex
dvips -Ppdf yourfile.dvi
ps2pdf yourfile.ps
</pre>
<p class="noindent">The <samp><span class="file">.dvi</span></samp> file created by this process will not contain
note heads. This is normal; if you follow the instructions, they
will be included in the <samp><span class="file">.ps</span></samp> and <samp><span class="file">.pdf</span></samp> files.
<p>Running <samp><span class="command">dvips</span></samp> may produce some warnings about fonts; these
are harmless and may be ignored. If you are running <samp><span class="command">latex</span></samp> in
twocolumn mode, remember to add <code>-t landscape</code> to the
<samp><span class="command">dvips</span></samp> options.
<h5 class="subsubheading">Texinfo</h5>
<p>To produce a Texinfo document (in any output format), follow the normal
procedures for Texinfo; this is, either call <samp><span class="command">texi2pdf</span></samp> or
<samp><span class="command">texi2dvi</span></samp> or <samp><span class="command">makeinfo</span></samp>, depending on the output format
you want to create.
See the documentation of Texinfo for further details.
<h4 class="subheading">Command line options</h4>
<p><samp><span class="command">lilypond-book</span></samp> accepts the following command line options:
<dl>
<dt><code>-f </code><var>format</var><dt><code>--format=</code><var>format</var><dd>Specify the document type to process: <code>html</code>, <code>latex</code>,
<code>texi</code> (the default) or <code>docbook</code>. If this option is missing,
<samp><span class="command">lilypond-book</span></samp> tries to detect the format automatically, see
<a href="#Filename-extensions">Filename extensions</a>. Currently, <code>texi</code> is the same as
<code>texi-html</code>.
<!-- This complicated detail is not implemented, comment it out -jm -->
<br><dt><code>-F </code><var>filter</var><dt><code>--filter=</code><var>filter</var><dd>Pipe snippets through <var>filter</var>. <code>lilypond-book</code> will
not –filter and –process at the same time. For example,
<pre class="example"> lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
</pre>
<br><dt><code>-h</code><dt><code>--help</code><dd>Print a short help message.
<br><dt><code>-I </code><var>dir</var><dt><code>--include=</code><var>dir</var><dd>Add <var>dir</var> to the include path. <samp><span class="command">lilypond-book</span></samp> also looks
for already compiled snippets in the include path, and does not write
them back to the output directory, so in some cases it is necessary to
invoke further processing commands such as <samp><span class="command">makeinfo</span></samp> or
<samp><span class="command">latex</span></samp> with the same <code>-I </code><var>dir</var> options.
<br><dt><code>-o </code><var>dir</var><dt><code>--output=</code><var>dir</var><dd>Place generated files in directory <var>dir</var>. Running
<samp><span class="command">lilypond-book</span></samp> generates lots of small files that LilyPond will
process. To avoid all that garbage in the source directory, use the
<samp><span class="option">--output</span></samp> command line option, and change to that directory
before running <samp><span class="command">latex</span></samp> or <samp><span class="command">makeinfo</span></samp>.
<pre class="example"> lilypond-book --output=out yourfile.lytex
cd out
...
</pre>
<dt><code>--skip-lily-check</code><dd>Do not fail if no lilypond output is found. It is used for LilyPond
Info documentation without images.
<dt><code>--skip-png-check</code><dd>Do not fail if no PNG images are found for EPS files. It is used for
LilyPond Info documentation without images.
<dt><code>--lily-output-dir=</code><var>dir</var><dd>Write lily-XXX files to directory <var>dir</var>, link into <code>--output</code>
directory. Use this option to save building time for documents in
different directories which share a lot of identical snippets.
<dt><code>--info-images-dir=</code><var>dir</var><dd>Format Texinfo output so that Info will look for images of music in
<var>dir</var>.
<dt><code>--latex-program=</code><var>prog</var><dd>Run executable <samp><span class="command">prog</span></samp> instead of <samp><span class="command">latex</span></samp>. This is
useful if your document is processed with <samp><span class="command">xelatex</span></samp>, for
example.
<dt><code>--left-padding=</code><var>amount</var><dd>Pad EPS boxes by this much. <var>amount</var> is measured in millimeters,
and is 3.0 by default. This option should be used if the lines of
music stick out of the right margin.
<p>The width of a tightly clipped systems can vary, due to notation
elements that stick into the left margin, such as bar numbers and
instrument names. This option will shorten each line and move each
line to the right by the same amount.
<br><dt><code>-P </code><var>process</var><dt><code>--process=</code><var>command</var><dd>Process LilyPond snippets using <var>command</var>. The default command is
<code>lilypond</code>. <code>lilypond-book</code> will not <code>--filter</code> and
<code>--process</code> at the same time.
<br><dt><code>--pdf</code><dd>Create PDF files for use with PDFLaTeX.
<br><dt><code>-V</code><dt><code>--verbose</code><dd>Be verbose.
<br><dt><code>-v</code><dt><code>--version</code><dd>Print version information.
</dl>
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p>The Texinfo command <code>@pagesizes</code> is not interpreted. Similarly,
LaTeX commands that change margins and line widths after the preamble
are ignored.
<p>Only the first <code>\score</code> of a LilyPond block is processed.
<p><a name="Filename-extensions"></a>
<h3 class="section">4.5 Filename extensions</h3>
<p>You can use any filename extension for the input file, but if you do not
use the recommended extension for a particular format you may need to
manually specify the output format; for details, see <a href="#Invoking-lilypond_002dbook">Invoking lilypond-book</a>. Otherwise, <samp><span class="command">lilypond-book</span></samp> automatically
selects the output format based on the input filename's extension.
<blockquote>
<p><table summary=""><tr align="left"><td valign="top" width="20%"><strong>extension</strong> </td><td valign="top" width="50%"><strong>output format</strong>
<br></td></tr><tr align="left"><td valign="top" width="20%"><br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.html</span></samp> </td><td valign="top" width="50%">HTML
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.itely</span></samp> </td><td valign="top" width="50%">Texinfo
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.latex</span></samp> </td><td valign="top" width="50%">LaTeX
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.lytex</span></samp> </td><td valign="top" width="50%">LaTeX
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.lyxml</span></samp> </td><td valign="top" width="50%">DocBook
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.tely</span></samp> </td><td valign="top" width="50%">Texinfo
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.tex</span></samp> </td><td valign="top" width="50%">LaTeX
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.texi</span></samp> </td><td valign="top" width="50%">Texinfo
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.texinfo</span></samp> </td><td valign="top" width="50%">Texinfo
<br></td></tr><tr align="left"><td valign="top" width="20%"><samp><span class="file">.xml</span></samp> </td><td valign="top" width="50%">HTML
<br></td></tr></table>
</blockquote>
<p>If you use the same filename extension for the input file than the
extension <samp><span class="command">lilypond-book</span></samp> uses for the output file, and if the
input file is in the same directory as <samp><span class="command">lilypond-book</span></samp> working
directory, you must use <code>--output</code> option to make
<samp><span class="command">lilypond-book</span></samp> running, otherwise the will exit with an error
message like “Output would overwrite input file”.
<p><a name="Alternate-methods-of-mixing-text-and-music"></a>
<h3 class="section">4.6 Alternative methods of mixing text and music</h3>
<p>This section shows methods to integrate text and music, different than
the automated method with <samp><span class="command">lilypond-book</span></samp>.
<p><a name="Many-quotes-from-a-large-score"></a>
<h4 class="unnumberedsubsec">Many quotes from a large score</h4>
<p>If you need to quote many fragments from a large score, you can also use
the clip systems feature, see <a name="index-Extracting-fragments-of-music-60"></a><a href="lilypond-big-page.html#Extracting-fragments-of-music">Extracting fragments of music</a>.
<p><a name="Inserting-LilyPond-output-into-OpenOffice.org"></a>
<a name="Inserting-LilyPond-output-into-OpenOffice_002eorg"></a>
<h4 class="unnumberedsubsec">Inserting LilyPond output into OpenOffice.org</h4>
<p><a name="index-OpenOffice_002eorg-61"></a>
LilyPond notation can be added to OpenOffice.org with
<a href="http://ooolilypond.sourceforge.net">OOoLilyPond</a>.
<p><a name="Inserting-LilyPond-output-into-other-programs"></a>
<h4 class="unnumberedsubsec">Inserting LilyPond output into other programs</h4>
<p>To insert LilyPond output in other programs, use <code>lilypond</code>
instead of <code>lilypond-book</code>. Each example must be created
individually and added to the document; consult the documentation for
that program. Most programs will be able to insert LilyPond output in
<samp><span class="file">PNG</span></samp>, <samp><span class="file">EPS</span></samp>, or <samp><span class="file">PDF</span></samp> formats.
<p>To reduce the white space around your LilyPond score, use
the following options
<pre class="example">\paper{
indent=0\mm
line-width=120\mm
oddFooterMarkup=##f
oddHeaderMarkup=##f
bookTitleMarkup = ##f
scoreTitleMarkup = ##f
}
{ c1 }
</pre>
<p>To produce a useful <samp><span class="file">EPS</span></samp> file, use
<pre class="example">lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
<samp><span class="file">PNG</span></samp>:
lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
</pre>
<!-- *- coding: utf-8; mode: texinfo; -*- -->
<!-- This file is part of lilypond-program.tely -->
<!-- \version "2.11.51" -->
<p><a name="Converting-from-other-formats"></a>
<h2 class="chapter">5 Converting from other formats</h2>
<p>Music can be entered also by importing it from other formats. This
chapter documents the tools included in the distribution to do so.
There are other tools that produce LilyPond input, for example GUI
sequencers and XML converters. Refer to the
<a href="http://lilypond.org">website</a> for more details.
<p>These are separate programs from <samp><span class="command">lilypond</span></samp> itself, and are run
on the command-line; see <a href="#Command_002dline-usage">Command-line usage</a> for more information.
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p>We unfortunately do not have the resources to maintain these
programs; please consider them “as-is”. Patches are appreciated, but
bug reports will almost certainly not be resolved.
<p><a name="Invoking-midi2ly"></a>
<h3 class="section">5.1 Invoking <samp><span class="command">midi2ly</span></samp></h3>
<p><a name="index-MIDI-62"></a>
<samp><span class="command">midi2ly</span></samp> translates a Type 1 MIDI file to a LilyPond source
file.
<p>MIDI (Music Instrument Digital Interface) is a standard for digital
instruments: it specifies cabling, a serial protocol and a file
format. The MIDI file format is a de facto standard format for
exporting music from other programs, so this capability may come in
useful when importing files from a program that has a converter for a
direct format.
<p><samp><span class="command">midi2ly</span></samp> converts tracks into <a name="index-Staff-63"></a><a href="lilypond-internals-big-page.html#Staff">Staff</a> and
channels into <a name="index-Voice-64"></a><a href="lilypond-internals-big-page.html#Voice">Voice</a> contexts. Relative mode is used
for pitches, durations are only written when necessary.
<p>It is possible to record a MIDI file using a digital keyboard, and
then convert it to <samp><span class="file">.ly</span></samp>. However, human players are not
rhythmically exact enough to make a MIDI to LY conversion trivial.
When invoked with quantizing (<code>-s</code> and <code>-d</code> options)
<samp><span class="command">midi2ly</span></samp> tries to compensate for these timing errors, but is not
very good at this. It is therefore not recommended to use <samp><span class="command">midi2ly</span></samp>
for human-generated midi files.
<p>It is invoked from the command-line as follows,
<pre class="example">midi2ly [<var>option</var>]... <var>midi-file</var>
</pre>
<p>Note that by ‘command-line’, we mean the command line of the
operating system. See <a href="#Converting-from-other-formats">Converting from other formats</a>, for
more information about this.
<p>The following options are supported by <samp><span class="command">midi2ly</span></samp>.
<dl>
<dt><code>-a, --absolute-pitches</code><dd>Print absolute pitches.
<br><dt><code>-d, --duration-quant=</code><var>DUR</var><dd>Quantize note durations on <var>DUR</var>.
<br><dt><code>-e, --explicit-durations</code><dd>Print explicit durations.
<br><dt><code>-h,--help</code><dd>Show summary of usage.
<br><dt><code>-k, --key=</code><var>acc</var><code>[:</code><var>minor</var><code>]</code><dd>Set default key. <var>acc</var> > 0 sets number of sharps;
<var>acc</var> < 0 sets number of flats. A minor key is indicated by
<code>:1</code>.
<br><dt><code>-o, --output=</code><var>file</var><dd>Write output to <var>file</var>.
<br><dt><code>-s, --start-quant=</code><var>DUR</var><dd>Quantize note starts on DUR.
<br><dt><code>-t, --allow-tuplet=</code><var>DUR</var><code>*</code><var>NUM</var><code>/</code><var>DEN</var><dd>Allow tuplet durations <var>DUR</var>*<var>NUM</var>/<var>DEN</var>.
<br><dt><code>-V, --verbose</code><dd>Be verbose.
<br><dt><code>-v, --version</code><dd>Print version number.
<br><dt><code>-w, --warranty</code><dd>Show warranty and copyright.
<br><dt><code>-x, --text-lyrics</code><dd>Treat every text as a lyric.
</dl>
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p>Overlapping notes in an arpeggio will not be correctly rendered. The
first note will be read and the others will be ignored. Set them all
to a single duration and add phrase markings or pedal indicators.
<p><a name="Invoking-musicxml2ly"></a>
<h3 class="section">5.2 Invoking <code>musicxml2ly</code></h3>
<p><a href="http://www.recordare.com/xml.html">MusicXML</a> is an XML dialect
for representing music notation.
<p><samp><span class="command">musicxml2ly</span></samp> extracts the notes from part-wise MusicXML
files, and writes it to a .ly file. It is invoked from the command-line.
<p>Note that by ‘command-line’, we mean the command line of the
operating system. See <a href="#Converting-from-other-formats">Converting from other formats</a>, for
more information about this.
<p>The following options are supported by <samp><span class="command">musicxml2ly</span></samp>:
<dl>
<dt><code>-h,--help</code><dd>print usage and option summary.
<br><dt><code>-o,--output=</code><var>file</var><dd>set output filename to <var>file</var>. (default: print to stdout)
<br><dt><code>-v,--version</code><dd>print version information.
</dl>
<p><a name="Invoking-abc2ly"></a>
<h3 class="section">5.3 Invoking <code>abc2ly</code></h3>
<p><a name="index-ABC-65"></a>
ABC is a fairly simple ASCII based format. It is described at the ABC site:
<blockquote>
<a href="http://www.walshaw.plus.com/abc/abc2mtex/abc.txt">http://www.walshaw.plus.com/abc/abc2mtex/abc.txt</a>.
</blockquote>
<p><samp><span class="command">abc2ly</span></samp> translates from ABC to LilyPond. It is invoked as follows:
<pre class="example">abc2ly [<var>option</var>]... <var>abc-file</var>
</pre>
<p>The following options are supported by <samp><span class="command">abc2ly</span></samp>:
<dl>
<dt><code>-h,--help</code><dd>this help
<br><dt><code>-o,--output=</code><var>file</var><dd>set output filename to <var>file</var>.
<br><dt><code>-v,--version</code><dd>print version information.
</dl>
<p>There is a rudimentary facility for adding LilyPond code to the ABC
source file. If you say:
<pre class="example">%%LY voices \set autoBeaming = ##f
</pre>
<p>This will cause the text following the keyword ‘voices’ to be inserted
into the current voice of the LilyPond output file.
<p>Similarly,
<pre class="example">%%LY slyrics more words
</pre>
<p>will cause the text following the ‘slyrics’ keyword to be inserted
into the current line of lyrics.
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p>The ABC standard is not very ‘standard’. For extended features
(e.g., polyphonic music) different conventions exist.
<p>Multiple tunes in one file cannot be converted.
<p>ABC synchronizes words and notes at the beginning of a line;
<samp><span class="command">abc2ly</span></samp> does not.
<p><samp><span class="command">abc2ly</span></samp> ignores the ABC beaming.
<p><a name="Invoking-etf2ly"></a>
<h3 class="section">5.4 Invoking <samp><span class="command">etf2ly</span></samp></h3>
<p><a name="index-ETF-66"></a><a name="index-enigma-67"></a><a name="index-Finale-68"></a><a name="index-Coda-Technology-69"></a>
ETF (Enigma Transport Format) is a format used by Coda Music
Technology's Finale product. <samp><span class="command">etf2ly</span></samp> will convert part of an ETF
file to a ready-to-use LilyPond file.
<p>It is invoked from the command-line as follows.
<pre class="example">etf2ly [<var>option</var>]... <var>etf-file</var>
</pre>
<p>Note that by ‘command-line’, we mean the command line of the
operating system. See <a href="#Converting-from-other-formats">Converting from other formats</a>, for
more information about this.
<p>The following options are supported by <samp><span class="command">etf2ly</span></samp>:
<dl>
<dt><code>-h,--help</code><dd>this help
<br><dt><code>-o,--output=FILE</code><dd>set output filename to FILE
<br><dt><code>-v,--version</code><dd>version information
</dl>
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p>The list of articulation scripts is incomplete. Empty measures
confuse <samp><span class="command">etf2ly</span></samp>. Sequences of grace notes are ended improperly.
<p><a name="Generating-LilyPond-files"></a>
<h3 class="section">5.5 Generating LilyPond files</h3>
<p><a name="index-External-programs_002c-generating-LilyPond-files-70"></a>
LilyPond itself does not come with support for any other formats, but
there are some external tools that also generate LilyPond files.
<p>These tools include
<ul>
<li><a href="http://denemo.sourceforge.net/">Denemo</a>, a graphical score editor.
<li><a href="http://www.volny.cz/smilauer/rumor/rumor.html">Rumor</a>, a realtime
monophonic MIDI to LilyPond converter.
<li><a href="http://nicolas.sceaux.free.fr/lilypond/lyqi.html">lyqi</a>, an
Emacs major mode.
<li><a href="http://www.nongnu.org/xml2ly/">xml2ly</a>, which imports
<a href="http://www.musicxml.com/xml.html">MusicXML</a>
<li><a href="http://noteedit.berlios.de">NoteEdit</a>
which imports <a href="http://www.musicxml.com/xml.html">MusicXML</a>
<li><a href="http://www.rosegardenmusic.com">Rosegarden</a>,
which imports MIDI
<li><a href="http://common-lisp.net/project/fomus/">FOMUS</a>,
a LISP library to generate music notation
<li><a href="http://vsr.informatik.tu-chemnitz.de/staff/jan/nted/nted.xhtml">http://vsr.informatik.tu-chemnitz.de/staff/jan/nted/nted.xhtml</a>,
has experimental export for lilypond.
<li><a href="http://www.tuxguitar.com.ar/">http://www.tuxguitar.com.ar/</a>, can export to lilypond.
<li><a href="http://musescore.org">http://musescore.org</a> can also export to lilypond.
</ul>
<p><a name="GNU-Free-Documentation-License"></a>
<h2 class="appendix">Appendix A GNU Free Documentation License</h2>
<p><a name="index-FDL_002c-GNU-Free-Documentation-License-71"></a><div align="center">Version 1.1, March 2000</div>
<pre class="display">Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</pre>
<ol type=1 start=0>
<li>PREAMBLE
<p>The purpose of this License is to make a manual, textbook, or other
written document <dfn>free</dfn> in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.
<p>This License is a kind of ‘copyleft’, which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
<p>We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
<li>APPLICABILITY AND DEFINITIONS
<p>This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License. The ‘Document’, below, refers to any
such manual or work. Any member of the public is a licensee, and is
addressed as ‘you’.
<p>A ‘Modified Version’ of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
<p>A ‘Secondary Section’ is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
<p>The ‘Invariant Sections’ are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.
<p>The ‘Cover Texts’ are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.
<p>A ‘Transparent’ copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
not ‘Transparent’ is called ‘Opaque’.
<p>Examples of suitable formats for Transparent copies include plain
<span class="sc">ascii</span> without markup, Texinfo input format, LaTeX input format,
<acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available
<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym> designed
for human modification. Opaque formats include PostScript,
<acronym>PDF</acronym>, proprietary formats that can be read and edited only by
proprietary word processors, <acronym>SGML</acronym> or <acronym>XML</acronym> for which
the <acronym>DTD</acronym> and/or processing tools are not generally available,
and the machine-generated <acronym>HTML</acronym> produced by some word
processors for output purposes only.
<p>The ‘Title Page’ means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ‘Title Page’ means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
<li>VERBATIM COPYING
<p>You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
<p>You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
<li>COPYING IN QUANTITY
<p>If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
<p>If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
<p>If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.
<p>It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
<li>MODIFICATIONS
<p>You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
<ol type=A start=1>
<li>Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
<li>List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five).
<li>State on the Title page the name of the publisher of the
Modified Version, as the publisher.
<li>Preserve all the copyright notices of the Document.
<li>Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
<li>Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
<li>Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
<li>Include an unaltered copy of this License.
<li>Preserve the section entitled ‘History’, and its title, and add to
it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section entitled ‘History’ in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
<li>Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ‘History’ section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
<li>In any section entitled ‘Acknowledgments’ or ‘Dedications’,
preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgments
and/or dedications given therein.
<li>Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
<li>Delete any section entitled ‘Endorsements’. Such a section
may not be included in the Modified Version.
<li>Do not retitle any existing section as ‘Endorsements’
or to conflict in title with any Invariant Section.
</ol>
<p>If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
<p>You may add a section entitled ‘Endorsements’, provided it contains
nothing but endorsements of your Modified Version by various
parties—for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
<p>You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
<p>The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
<li>COMBINING DOCUMENTS
<p>You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.
<p>The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
<p>In the combination, you must combine any sections entitled ‘History’
in the various original documents, forming one section entitled
‘History’; likewise combine any sections entitled ‘Acknowledgments’,
and any sections entitled ‘Dedications’. You must delete all sections
entitled ‘Endorsements.’
<li>COLLECTIONS OF DOCUMENTS
<p>You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
<p>You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
<li>AGGREGATION WITH INDEPENDENT WORKS
<p>A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation. Such a compilation is called an ‘aggregate’, and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.
<p>If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.
<li>TRANSLATION
<p>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License provided that you also include the
original English version of this License. In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.
<li>TERMINATION
<p>You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
<li>FUTURE REVISIONS OF THIS LICENSE
<p>The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
<p>Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ‘or any later version’ applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
</ol>
<h4 class="subheading">ADDENDUM: How to use this License for your documents</h4>
<p>To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
<pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being <var>list their titles</var>, with the
Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts being <var>list</var>.
A copy of the license is included in the section entitled ‘GNU
Free Documentation License’.
</pre>
<p>If you have no Invariant Sections, write ‘with no Invariant Sections’
instead of saying which ones are invariant. If you have no
Front-Cover Texts, write ‘no Front-Cover Texts’ instead of
‘Front-Cover Texts being <var>list</var>’; likewise for Back-Cover Texts.
<p>If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
<!-- Local Variables: -->
<!-- ispell-local-pdict: "ispell-dict" -->
<!-- End: -->
<p><a name="LilyPond-index"></a>
<h2 class="appendix">Appendix B LilyPond index</h2>
<ul class="index-cp" compact>
<li><a href="#index-g_t_005cheader-in-_0040LaTeX_007b_007d-documents-52">\header in LaTeX documents</a>: <a href="#LaTeX">LaTeX</a></li>
<li><a href="#index-ABC-65">ABC</a>: <a href="#Invoking-abc2ly">Invoking abc2ly</a></li>
<li><a href="#index-About-the-documentation-1"><code>About the documentation</code></a>: <a href="#Top">Top</a></li>
<li><a href="#index-bugs-37">bugs</a>: <a href="#Reporting-bugs">Reporting bugs</a></li>
<li><a href="#index-call-trace-31">call trace</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-Coda-Technology-69">Coda Technology</a>: <a href="#Invoking-etf2ly">Invoking etf2ly</a></li>
<li><a href="#index-coloring_002c-syntax-9">coloring, syntax</a>: <a href="#Text-editor-support">Text editor support</a></li>
<li><a href="#index-command-line-options-14">command line options</a>: <a href="#Invoking-lilypond">Invoking lilypond</a></li>
<li><a href="#index-convert_002dly-36">convert-ly</a>: <a href="#Updating-files-with-convert_002dly">Updating files with convert-ly</a></li>
<li><a href="#index-docbook-44">docbook</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-DocBook_002c-music-in-48">DocBook, music in</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-documents_002c-adding-music-to-45">documents, adding music to</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-dvips-58">dvips</a>: <a href="#Invoking-lilypond_002dbook">Invoking lilypond-book</a></li>
<li><a href="#index-editors-4">editors</a>: <a href="#Text-editor-support">Text editor support</a></li>
<li><a href="#index-emacs-6">emacs</a>: <a href="#Text-editor-support">Text editor support</a></li>
<li><a href="#index-enigma-67">enigma</a>: <a href="#Invoking-etf2ly">Invoking etf2ly</a></li>
<li><a href="#index-error-28">error</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-error-messages-26">error messages</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-errors_002c-message-format-34">errors, message format</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-ETF-66">ETF</a>: <a href="#Invoking-etf2ly">Invoking etf2ly</a></li>
<li><a href="#index-External-programs_002c-generating-LilyPond-files-70">External programs, generating LilyPond files</a>: <a href="#Generating-LilyPond-files">Generating LilyPond files</a></li>
<li><a href="#index-Extracting-fragments-of-music-60"><code>Extracting fragments of music</code></a>: <a href="#Many-quotes-from-a-large-score">Many quotes from a large score</a></li>
<li><a href="#index-fatal-error-29">fatal error</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-FDL_002c-GNU-Free-Documentation-License-71">FDL, GNU Free Documentation License</a>: <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></li>
<li><a href="#index-file-searching-22">file searching</a>: <a href="#Command-line-options">Command line options</a></li>
<li><a href="#index-file-size_002c-output-11">file size, output</a>: <a href="#Point-and-click">Point and click</a></li>
<li><a href="#index-Finale-68">Finale</a>: <a href="#Invoking-etf2ly">Invoking etf2ly</a></li>
<li><a href="#index-First-steps-12"><code>First steps</code></a>: <a href="#Normal-usage">Normal usage</a></li>
<li><a href="#index-html-43">html</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-HTML_002c-music-in-46">HTML, music in</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-invoking-dvips-59">invoking dvips</a>: <a href="#Invoking-lilypond_002dbook">Invoking lilypond-book</a></li>
<li><a href="#index-Invoking-LilyPond-13">Invoking LilyPond</a>: <a href="#Invoking-lilypond">Invoking lilypond</a></li>
<li><a href="#index-LANG-24">LANG</a>: <a href="#Environment-variables">Environment variables</a></li>
<li><a href="#index-latex-40">latex</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-g_t_0040LaTeX_007b_007d_002c-music-in-49">LaTeX, music in</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-LILYPOND_005fDATADIR-25">LILYPOND_DATADIR</a>: <a href="#Environment-variables">Environment variables</a></li>
<li><a href="#index-MIDI-62">MIDI</a>: <a href="#Invoking-midi2ly">Invoking midi2ly</a></li>
<li><a href="#index-modes_002c-editor-7">modes, editor</a>: <a href="#Text-editor-support">Text editor support</a></li>
<li><a href="#index-musicology-50">musicology</a>: <a href="#An-example-of-a-musicological-document">An example of a musicological document</a></li>
<li><a href="#index-OpenOffice_002eorg-61">OpenOffice.org</a>: <a href="#Inserting-LilyPond-output-into-OpenOffice_002eorg">Inserting LilyPond output into OpenOffice.org</a></li>
<li><a href="#index-options_002c-command-line-15">options, command line</a>: <a href="#Invoking-lilypond">Invoking lilypond</a></li>
<li><a href="#index-outline-fonts-56">outline fonts</a>: <a href="#Invoking-lilypond_002dbook">Invoking lilypond-book</a></li>
<li><a href="#index-output-format_002c-setting-21">output format, setting</a>: <a href="#Command-line-options">Command line options</a></li>
<li><a href="#index-point-and-click-10">point and click</a>: <a href="#Point-and-click">Point and click</a></li>
<li><a href="#index-point-and-click_002c-command-line-17">point and click, command line</a>: <a href="#Command-line-options">Command line options</a></li>
<li><a href="#index-PostScript-output-18">PostScript output</a>: <a href="#Command-line-options">Command line options</a></li>
<li><a href="#index-preview-image-54">preview image</a>: <a href="#HTML">HTML</a></li>
<li><a href="#index-Programming-error-33">Programming error</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-reporting-bugs-38">reporting bugs</a>: <a href="#Reporting-bugs">Reporting bugs</a></li>
<li><a href="#index-Scheme-dump-20">Scheme dump</a>: <a href="#Command-line-options">Command line options</a></li>
<li><a href="#index-Scheme-error-32">Scheme error</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-search-path-23">search path</a>: <a href="#Command-line-options">Command line options</a></li>
<li><a href="#index-Staff-63"><code>Staff</code></a>: <a href="#Invoking-midi2ly">Invoking midi2ly</a></li>
<li><a href="#index-SVG-_0028Scalable-Vector-Graphics_0029-19">SVG (Scalable Vector Graphics)</a>: <a href="#Command-line-options">Command line options</a></li>
<li><a href="#index-switches-16">switches</a>: <a href="#Invoking-lilypond">Invoking lilypond</a></li>
<li><a href="#index-syntax-coloring-8">syntax coloring</a>: <a href="#Text-editor-support">Text editor support</a></li>
<li><a href="#index-texi-42">texi</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-texinfo-39">texinfo</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-Texinfo_002c-music-in-47">Texinfo, music in</a>: <a href="#LilyPond_002dbook">LilyPond-book</a></li>
<li><a href="#index-thumbnail-55">thumbnail</a>: <a href="#HTML">HTML</a></li>
<li><a href="#index-titling-and-lilypond_002dbook-51">titling and lilypond-book</a>: <a href="#LaTeX">LaTeX</a></li>
<li><a href="#index-titling-in-HTML-53">titling in HTML</a>: <a href="#HTML">HTML</a></li>
<li><a href="#index-trace_002c-Scheme-30">trace, Scheme</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-type1-fonts-57">type1 fonts</a>: <a href="#Invoking-lilypond_002dbook">Invoking lilypond-book</a></li>
<li><a href="#index-Updating-a-LilyPond-file-35">Updating a LilyPond file</a>: <a href="#Updating-files-with-convert_002dly">Updating files with convert-ly</a></li>
<li><a href="#index-URL-3">URL</a>: <a href="#Top">Top</a></li>
<li><a href="#index-vim-5">vim</a>: <a href="#Text-editor-support">Text editor support</a></li>
<li><a href="#index-Voice-64"><code>Voice</code></a>: <a href="#Invoking-midi2ly">Invoking midi2ly</a></li>
<li><a href="#index-warning-27">warning</a>: <a href="#Error-messages">Error messages</a></li>
<li><a href="#index-web-site-2">web site</a>: <a href="#Top">Top</a></li>
</ul><div class="footnote">
<hr>
<a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> On UNIX, this file is found either in
<samp><span class="file">/etc/xpdfrc</span></samp> or as <samp><span class="file">.xpdfrc</span></samp> in your home directory.</p>
<p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> The status of
GUILE is not reset after processing a <code>.ly</code> file, so be careful
not to change any system defaults from within Scheme.</p>
<p class="footnote"><small>[<a name="fn-3" href="#fnd-3">3</a>]</small> This
tutorial is processed with Texinfo, so the example gives slightly
different results in layout.</p>
<p class="footnote"><small>[<a name="fn-4" href="#fnd-4">4</a>]</small> Note
that PDFLaTeX and LaTeX may not be both usable to compile any
LaTeX document, that is why we explain the two ways.</p>
<hr></div>
<!-- footer_tag -->
<div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;">
<p>
<font size="-1">
This page is for LilyPond-2.11.57 (development-branch).
<br>
<address>
Report errors to <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs</a>. </address>
<br>
Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome.
</font>
</p>
</div>
</BODY></html>
<!--
Local Variables:
coding: utf-8
End:
-->
