# LilyPond — Usage

 This file explains how to execute the programs distributed with LilyPond version 2.18.2. In addition, it suggests some “best practices” for efficient usage.
 For more information about how this manual fits with the other documentation, or to read this manual in other formats, see Manuals. If you are missing any manuals, the complete documentation can be found at http://www.lilypond.org/.

# 1. Running lilypond

This chapter details the technicalities of running LilyPond.

## 1.1 Normal usage

Most users run LilyPond through a GUI; if you have not done so already, please read the Tutorial. If you use an alternate editor to write lilypond files, see the documentation for that program.

## 1.2 Command-line usage

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 midi2ly) which are only available on the command-line.

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’. Some additional setup is required for MacOS X users; please see MacOS X.

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.

### Invoking lilypond

The lilypond executable may be called as follows from the command line.

lilypond [option]… file…


When invoked with a filename that has no extension, the ‘.ly’ extension is tried first. To read input from stdin, use a dash (-) for file.

When ‘filename.ly’ is processed it will produce ‘filename.ps’ and ‘filename.pdf’ as output. Several files can be specified; they will each be processed independently. 1

If ‘filename.ly’ contains more than one \book block, then the rest of the scores will be output in numbered files, starting with ‘filename-1.pdf’. In addition, the value of output-suffix will be inserted between the basename and the number. An input file containing

#(define output-suffix "violin")
\score { … }
#(define output-suffix "cello")
\score { … }


will output base-violin.pdf’ and base-cello-1.pdf’.

#### Standard shell commands

If your shell (i.e. command window) supports normal redirects, then you might find it useful to use the following commands to redirect console output to a file:

• lilypond file.ly 1>stdout.log to redirect normal output
• lilypond file.ly 2>stderr.log to redirect error messages
• lilypond file.ly &>all.log to redirect all output

Consult the documentation for your shell to see if it supports these options, or if the syntax is different. Note that these are shell commands and have nothing to do with lilypond.

### Basic command line options for LilyPond

The following options are supported:

-d, --define-default=var=val
-e, --evaluate=expr

Evaluate the Scheme expr before parsing any ‘.ly’ files. Multiple ‘-e’ options may be given, they will be evaluated sequentially.

The expression will be evaluated in the guile-user module, so if you want to use definitions in expr, use

lilypond -e '(define-public a 42)'


on the command-line, and include

#(use-modules (guile-user))


at the top of the .ly file.

Note: Windows users must use double quotes instead of single quotes.

-f, --format=format

which formats should be written. Choices for format are ps, pdf, and png.

Example: lilypond -fpng filename.ly

-h, --help

Show a summary of usage.

-H, --header=FIELD

Dump a header field to file ‘BASENAME.FIELD’.

-i, --init=file

Set init file to file (default: ‘init.ly’).

-I, --include=directory

Add directory to the search path for input files.

Multiple -I options may be given. The search will start in the first defined directory, and if the file to be included is not found the search will continue in subsequent directories.

-j, --jail=user,group,jail,dir

Run lilypond in a chroot jail.

The ‘--jail’ option provides a more flexible alternative to ‘-dsafe’, when LilyPond formatting is being provided via a web server, or whenever LilyPond executes commands sent by external sources (see Advanced command line options for LilyPond).

It works by changing the root of lilypond to jail 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 dir. This setup guarantees that it is not possible (at least in theory) to escape from the jail. Note that for ‘--jail’ to work, lilypond must be run as root, which is usually accomplished in a safe way using sudo.

Setting up a jail can be a relatively complex matter, as we must be sure that LilyPond is able to find whatever it needs to compile the source inside the jail itself. A typical chroot jail will comprise the following steps:

Setting up a separate filesystem

A separate filesystem should be created for LilyPond, so that it can be mounted with safe options such as noexec, nodev, and nosuid. 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.

Setting up a separate user

A separate user and group (say, lily/lily) 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 dir.

Preparing the jail

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., ‘/usr/share/lilypond’) should be copied.

If problems arise, the simplest way to trace them down is to run LilyPond using strace, which will allow you to determine which files are missing.

Running LilyPond

In a jail mounted with noexec 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 have already mentioned, it must be run with superuser privileges (which, of course, it will lose immediately), possibly using sudo. It is also good practice to limit the number of seconds of CPU time LilyPond can use (e.g., using ulimit -t), and, if your operating system supports it, the amount of memory that can be allocated. Also see LilyPond in chroot jail.

-l, --loglevel=LEVEL

Set the verbosity of the console output to LEVEL. Possible values are:

NONE

No output at all, not even error messages.

ERROR

Only error messages, no warnings or progress messages.

WARN

Warnings and error messages, no progress.

BASIC_PROGRESS

Basic progress messages (success), warnings and errors.

PROGRESS

All progress messages, warnings and errors.

INFO (default)

Progress messages, warnings, errors and further execution information.

DEBUG

All possible messages, including verbose debug output.

-o, --output=FILE or FOLDER

Set the default output file to FILE or, if a folder with that name exists, direct the output to FOLDER, taking the file name from the input file. The appropriate suffix will be added (e.g. .pdf for pdf) in both cases.

--ps

Generate PostScript.

--png

Generate pictures of each page, in PNG format. This implies ‘--ps’. The resolution in DPI of the image may be set with

-dresolution=110

--pdf

Generate PDF. This implies ‘--ps’.

-v, --version

Show version information.

-V, --verbose

Be verbose: show full paths of all files read, and give timing information.

-w, --warranty

Show the warranty with which GNU LilyPond comes. (It comes with NO WARRANTY!)

### Advanced command line options for LilyPond

-d[option-name]=[value],--define-default=[option-name]=[value]

This sets the equivalent internal Scheme function to value.

-dbackend=svg


If a value is not supplied, then the default value is used. The prefix no- may be added to option-name to switch ‘off’ an option, e.g.

-dpoint-and-click=#f


is the same as

-dno-point-and-click


The following are supported along with their respective default values:

 Symbol Value Explanation/Options anti-alias-factor 1 Render at higher resolution (using given factor) and scale down result to prevent ‘jaggies’ in PNG images. aux-files #t Create .tex, .texi, .count files in the EPS backend. backend ps Select backend. Postscript files (default) include TTF, Type1 and OTF fonts. No subsetting of these fonts is done. Using ‘oriental’ character sets can lead to very large files. eps Encapsulated PostScript. This dumps every page (system) as a separate ‘EPS’ file, without fonts, and as one collated ‘EPS’ file with all pages (systems) including fonts. Used as default by lilypond-book. null Do not output a printed score; has the same effect as -dno-print-pages. svg Scalable Vector Graphics. This creates a single SVG file, without embedded fonts, for every page of output. It is recommended to install the Century Schoolbook fonts, included with your LilyPond installation, for optimal rendering. Under UNIX, simply copy these fonts from the LilyPond directory (typically ‘/usr/share/lilypond/VERSION/fonts/otf/’) to ‘~/.fonts/’. The SVG output should be compatible with any SVG editor or user agent. There is also an option svg-woff (below) for use of woff font files in the SVG backend. scm Dump of the raw, internal Scheme-based drawing commands. check-internal-types #f Check every property assignment for types. clip-systems #f Generate cut-out snippets of a score. datadir Prefix for data files (read-only). debug-gc #f Dump memory debugging statistics. debug-gc-assert-parsed-dead #f For memory debugging: Ensure that all references to parsed objects are dead. This is an internal option, and is switched on automatically for -ddebug-gc'. debug-lexer #f Debug the flex lexer. debug-page-breaking-scoring #f Dump scores for many different page breaking configurations. debug-parser #f Debug the bison parser. debug-property-callbacks #f Debug cyclic callback chains. debug-skylines #f Debug skylines. delete-intermediate-files #t Delete the unusable, intermediate .ps files created during compilation. dump-cpu-profile #f Dump timing information (system-dependent). dump-profile #f Dump memory and time information for each file. dump-signatures #f Dump output signatures of each system. Used for regression testing. eps-box-padding #f Pad left edge of the output EPS bounding box by the given amount (in mm). gs-load-fonts #f Load fonts via Ghostscript. gs-load-lily-fonts #f Load only the LilyPond fonts via Ghostscript. gui #f Runs silently and redirect all output to a log file.

Note to Windows users: By default lilypond.exe outputs all progress information to the command window, lilypond-windows.exe does not and returns a prompt, with no progress information, immediately at the command line. The ‘-dgui’ option can be used in this case to redirect output to a log file.

 help #f Show this help. include-book-title-preview #t Include book titles in preview images. include-eps-fonts #t Include fonts in separate-system EPS files. include-settings #f Include file for global settings, this is included before the score is processed. job-count #f Process in parallel, using the given number of jobs. log-file #f [file] If string FOO is given as a second argument, redirect output to the log file FOO.log. max-markup-depth 1024 Maximum depth for the markup tree. If a markup has more levels, assume it will not terminate on its own, print a warning and return a null markup instead. midi-extension "midi" Set the default file extension for MIDI output file to given string. music-strings-to-paths #f Convert text strings to paths when glyphs belong to a music font. paper-size \"a4\" Set default paper size. Note the string must be enclosed in escaped double quotes. pixmap-format png16m Set GhostScript’s output format for pixel images. point-and-click #f Add ‘point & click’ links to PDF output. See Point and click. preview #f Create preview images in addition to normal output.

This option is supported by all backends; pdf, png, ps, eps and svg, but not scm. It generates an output file, in the form myFile.preview.extension, containing the titles and the first system of music. If \book or \bookpart blocks are used, the titles of \book, \bookpart or \score will appear in the output, including the first system of every \score block if the \paper variable print-all-headers is set to #t.

To suppress the usual output, use the ‘-dprint-pages’ or ‘-dno-print-pages’ options according to your requirements.

 print-pages #t Generate full pages, the default. ‘-dno-print-pages’ is useful in combination with ‘-dpreview’. profile-property-accesses #f Keep statistics of get_property() function calls. protected-scheme-parsing #t Continue when errors in inline scheme are caught in the parser. If set to #f, halt on errors and print a stack trace. read-file-list #f [file] Specify name of a file which contains a list of input files to be processed. relative-includes #f When processing an \include command, look for the included file relative to the current file (instead of the root file). resolution 101 Set resolution for generating PNG pixmaps to given value (in dpi). safe #f Do not trust the .ly input.

When LilyPond formatting is available through a web server, either the ‘--safe’ or the ‘--jail’ option MUST be passed. The ‘--safe’ option will prevent inline Scheme code from wreaking havoc, e.g,

#(system "rm -rf /")
{
cp -L \/\1\2 \1\2/' | sed 's/\t\/$$.*\/$$$$.*$$ (.*)$/mkdir -p \ \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done  ### Example script for 32-bit Ubuntu 8.04 #!/bin/sh ## defaults set here username=lily home=/home loopdevice=/dev/loop0 jaildir=/mnt/lilyloop # the prefix (without the leading slash!) lilyprefix=usr/local # the directory where lilypond is installed on the system lilydir=/$lilyprefix/lilypond/

userhome=$home/$username
loopfile=$userhome/loopfile adduser$username
dd if=/dev/zero of=$loopfile bs=1k count=200000 mkdir$jaildir
losetup $loopdevice$loopfile
mkfs -t ext3 $loopdevice 200000 mount -t ext3$loopdevice $jaildir mkdir$jaildir/lilyhome
chown $username$jaildir/lilyhome
cd $jaildir mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts$lilyprefix tmp
chmod a+w tmp

cp -r -L $lilydir$lilyprefix
cp -L /bin/sh /bin/rm bin
cp -L /usr/bin/convert /usr/bin/gs usr/bin
cp -L /usr/share/fonts/truetype usr/share/fonts

# Now the library copying magic
for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
"/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \ \/$$.*\/$$$$[^(]*$$.*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed \ 's/\t\/$$.*\/$$$$.*$$ (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
| sed '/.*=>.*/d'; done | sh -s

# The shared files for ghostscript...
cp -L -r /usr/share/ghostscript usr/share
# The shared files for ImageMagick
cp -L -r /usr/lib/ImageMagick* usr/lib

### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
### you should be able to run:
### Note that /$lilyprefix/bin/lilypond is a script, which sets the ### LD_LIBRARY_PATH - this is crucial /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly


## 1.3 Error messages

Different error messages can appear while compiling a file:

Warning

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.

Error

Something is definitely wrong. The current processing step (parsing, interpreting, or formatting) will be finished, but the next step will be skipped.

Fatal error

Something is definitely wrong, and LilyPond cannot continue. This happens rarely. The most usual cause is misinstalled fonts.

Scheme error

Errors that occur while executing Scheme code are caught by the Scheme interpreter. If running with the verbose option (‘-V’ or ‘--verbose’) then a call trace of the offending function call is printed.

Programming error

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.

Aborted (core dumped)

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.

If warnings and errors can be linked to some part of the input file, then error messages have the following form

filename:lineno:columnno: message
offending input line


A line-break is inserted in the offending line to indicate the column where the error was found. For example,

test.ly:2:19: error: not a duration: 5
{ c'4 e'
5 g' }


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.

## 1.4 Common errors

The error conditions described below occur often, yet the cause is not obvious or easily found. Once seen and understood, they are easily handled.

### Music runs off the page

Music running off the page over the right margin or appearing unduly compressed is almost always due to entering an incorrect duration on a note, causing the final note in a measure to extend over the bar line. It is not invalid if the final note in a measure does not end on the automatically entered bar line, as the note is simply assumed to carry over into the next measure. But if a long sequence of such carry-over measures occurs the music can appear compressed or may flow off the page because automatic line breaks can be inserted only at the end of complete measures, i.e., where all notes end before or at the end of the measure.

Note: An incorrect duration can cause line breaks to be inhibited, leading to a line of highly compressed music or music which flows off the page.

The incorrect duration can be found easily if bar checks are used, see Bar and bar number checks.

If you actually intend to have a series of such carry-over measures you will need to insert an invisible bar line where you want the line to break. For details, see Bar lines.

### An extra staff appears

If contexts are not created explicitly with \new or \context, they will be silently created as soon as a command is encountered which cannot be applied to an existing context. In simple scores the automatic creation of contexts is useful, and most of the examples in the LilyPond manuals take advantage of this simplification. But occasionally the silent creation of contexts can give rise to unexpected new staves or scores. For example, it might be expected that the following code would cause all note heads within the following staff to be colored red, but in fact it results in two staves with the note heads remaining the default black in the lower staff.

\override Staff.NoteHead.color = #red
\new Staff { a }


This is because a Staff context does not exist when the override is processed, so one is implicitly created and the override is applied to it, but then the \new Staff command creates another, separate, staff into which the notes are placed. The correct code to color all note heads red is

\new Staff {
a
}


As a second example, if a \relative command is placed inside a \repeat command, two staves result, the second offset from the first, because the \repeat command generates two \relative blocks, which each implicitly create Staff and Voice blocks.

\repeat unfold 2 {
\relative c' { c4 d e f }
}


Explicitly instantiating the Voice context fixes the problem:

\new Voice {
\repeat unfold 2 {
\relative c' { c4 d e f }
}
}


### Error message Unbound variable %

This error message will appear at the bottom of the console output or log file together with a “GUILE signalled an error …” message every time a Scheme routine is called which (invalidly) contains a LilyPond rather than a Scheme comment.

LilyPond comments begin with a percent sign, (%), and must not be used within Scheme routines. Scheme comments begin with a semi-colon, (;).

### Error message FT_Get_Glyph_Name

This error messages appears in the console output or log file if an input file contains a non-ASCII character and was not saved in UTF-8 encoding. For details, see Text encoding.

### Warning staff affinities should only decrease

This warning can appear if there are no staves in the printed output, for example if there are just a ChordName context and a Lyrics context as in a lead sheet. The warning messages can be avoided by making one of the contexts behave as a staff by inserting

\override VerticalAxisGroup.staff-affinity = ##f


at its start. For details, see “Spacing of non-staff lines” in Flexible vertical spacing within systems.

### Error message unexpected \new

A \score block must contain a single music expression. If instead it contains several \new Staff, \new StaffGroup or similar contexts introduced with \new without them being enclosed in either curly brackets, { … }, or double angle brackets, << … >>, like this:

\score {
% Invalid! Generates error: syntax error, unexpected \new
\new Staff { … }
\new Staff { … }
}


the error message will be produced.

To avoid the error, enclose all the \new statements in curly or double angle brackets.

Using curly brackets will introduce the \new statements sequentially:

\score {
{
\new Staff { a' a' a' a' }
\new Staff { g' g' g' g' }
}
}


but more likely you should be using double angle brackets so the new staves are introduced in parallel, i.e. simultaneously:

\score {
<<
\new Staff { a' a' a' a' }
\new Staff { g' g' g' g' }
>>
}


# 2. Updating files with convert-ly

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 convert-ly can be used for upgrading files to newer versions of LilyPond.

## 2.1 Why does the syntax change?

The LilyPond input syntax occasionally changes. As LilyPond itself improves, the syntax (input language) is modified accordingly. Sometimes these changes are made to make the input easier to read and write or sometimes the changes are made to accommodate new features of LilyPond.

For example, all \paper and \layout property names are supposed to be written in the form first-second-third. However, in version 2.11.60, we noticed that the printallheaders property did not follow this convention. Should we leave it alone (confusing new users who must deal with an inconsistent input format), or change it (annoying old users with existing scores)? In this case, we decided to change the name to print-all-headers. Fortunately, this change can be automated with our convert-ly tool.

Unfortunately, convert-ly cannot handle all input changes. For example, in LilyPond 2.4 and earlier, accents and non-English letters were entered using LaTeX – displaying the French word for Christmas was entered as No\"el. But in LilyPond 2.6 and above, the special ë must be entered directly into the LilyPond file as an UTF-8 character. convert-ly cannot change all the LaTeX special characters into UTF-8 characters; you must manually update your old LilyPond input files.

The conversion rules of convert-ly work using text pattern matching and replacement rather than a thorough understanding of LilyPond. This has several consequences:

• The reliability of the conversion depends on the quality of each applied rule set and on the complexity of the respective change. Sometimes conversions may require manual fixes, so the old version should be kept available for comparison.
• Only conversions to newer formats are possible: there are no rule sets for downgrading. So the main working copy of a LilyPond file should only be upgraded when older versions of LilyPond no longer need to be supported. Version control systems such as Git might help with maintaining multiple versions.
• LilyPond and Scheme themselves are quite robust against creatively placed and omitted spaces, but the rules used by convert-ly tend to make some stylistic assumptions. Following the style used in the manuals is the safest bet for painless upgrades, particularly as the manuals themselves are upgraded using convert-ly.

## 2.2 Invoking convert-ly

convert-ly uses \version statements in the input file to detect the old version number. In most cases, to upgrade your input file it is sufficient to run

convert-ly -e myfile.ly


in the directory containing the file. This will upgrade ‘myfile.ly’ in-place and preserve the original file in ‘myfile.ly~’.

Note: convert-ly always converts up to the last syntax change handled by it. This means that the version number left in the file is usually lower than the version of convert-ly itself.

To convert all the input files in a directory together use

convert-ly -e *.ly


Alternatively, if you want to specify a different name for the upgraded file, preserving the original file and name unchanged, use

convert-ly myfile.ly > mynewfile.ly


The program will list the version numbers for which conversions have been made. If no version numbers are listed the file is already up to date.

MacOS X users may execute these commands under the menu entry Compile > Update syntax.

Windows users should enter these commands in a Command Prompt window, which is usually found under Start > Accessories > Command Prompt.

## 2.3 Command line options for convert-ly

The program is invoked as follows:

convert-ly [option]… filename…


The following options can be given:

-d, --diff-version-update

increase the \version string only if the file has actually been changed. In that case, the version header will correspond to the version after the last actual change. An unstable version number will be rounded up to the next stable version number unless that would exceed the target version number. Without this option, the version will instead reflect the last attempted conversion.

-e, --edit

Apply the conversions direct to the input file, modifying it in-place. The original file is renamed as ‘myfile.ly~’. This backup file may be a hidden file on some operating systems.

-b, --backup-numbered

When used with the ‘-e’ option, number the backup files so that no previous version is overwritten. The backup files may be hidden on some operating systems.

-f, --from=from-patchlevel

Set the version to convert from. If this is not set, convert-ly will guess this, on the basis of \version strings in the file. E.g. ‘--from=2.10.25

-h, --help

Print usage help.

-l loglevel, --loglevel=loglevel

Set the output verbosity to loglevel. Possible values, in upper case, are PROGRESS (the default), NONE, WARNING, ERROR and DEBUG.

-n, --no-version

Normally, convert-ly adds a \version indicator to the output. Specifying this option suppresses this.

-s, --show-rules

Show all known conversions and exit.

-t, --to=to-patchlevel

Explicitly set which \version to convert to, otherwise the default is the most current value. It must be higher than the starting version.

convert-ly --to=2.14.1 myfile.ly


To upgrade LilyPond fragments in texinfo files, use

convert-ly --from=… --to=… --no-version *.itely


To see the changes in the LilyPond syntax between two versions, use

convert-ly --from=… --to=… -s


## 2.4 Problems running convert-ly

When running convert-ly in a Command Prompt window under Windows on a file which has spaces in the filename or in the path to it, it is necessary to surround the entire input file name with three (!) sets of double quotes:

convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"


If the simple convert-ly -e *.ly command fails because the expanded command line becomes too long, the convert-ly command may be placed in a loop instead. This example for UNIX will upgrade all ‘.ly’ files in the current directory


urlCommand     "lilypond-invoke-editor %s"


If you are using Ubuntu, it is likely that the version of Xpdf installed with your system crashes on every PDF file: this state has been persisting for several years and is due to library mismatches. Your best bet is to install a current ‘xpdf’ package and the corresponding ‘libpoppler’ package from Debian instead. Once you have tested that this works, you might want to use

sudo apt-mark hold xpdf


in order to keep Ubuntu from overwriting it with the next ‘update’ of its crashing package.

#### Using GNOME 2

For using GNOME 2 (and PDF viewers integrated with it), the magic invocation for telling the system about the ‘textedit:’ URI is

gconftool-2 -t string -s /desktop/gnome/url-handlers/textedit/command "lilypond-invoke-editor %s"
gconftool-2 -s /desktop/gnome/url-handlers/textedit/needs_terminal false -t bool
gconftool-2 -t bool -s /desktop/gnome/url-handlers/textedit/enabled true


After that invocation,

gnome-open textedit:///etc/issue:1:0:0


should call ‘lilypond-invoke-editor’ for opening files.

#### Using GNOME 3

In GNOME 3, URIs are handled by the ‘gvfs’ layer rather than by ‘gconf’. Create a file in a local directory such as ‘/tmp’ that is called ‘lilypond-invoke-editor.desktop’ and has the contents

[Desktop Entry]
Version=1.0
Name=lilypond-invoke-editor
GenericName=Textedit URI handler
Comment=URI handler for textedit:
Exec=lilypond-invoke-editor %u
Terminal=false
Type=Application
MimeType=x-scheme-handler/textedit;
Categories=Editor
NoDisplay=true


and then execute the commands

xdg-desktop-menu install ./lilypond-invoke-editor.desktop
xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit


After that invocation,

gnome-open textedit:///etc/issue:1:0:0


should call ‘lilypond-invoke-editor’ for opening files.

#### Extra configuration for Evince

If gnome-open works, but Evince still refuses to open point and click links due to denied permissions, you might need to change the Apparmor profile of Evince which controls the kind of actions Evince is allowed to perform.

For Ubuntu, the process is to edit the file ‘/etc/apparmor.d/local/usr.bin.evince’ and append the following lines:

# For Textedit links
/usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,


sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince


Now Evince should be able to open point and click links. It is likely that similar configurations will work for other viewers.

### Enabling point and click

Point and click functionality is enabled by default when creating PDF files.

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

\pointAndClickOff


in a ‘.ly’ file. Point and click may be explicitly enabled with

\pointAndClickOn


Alternately, you may disable point and click with a command-line option:

lilypond -dno-point-and-click file.ly


Note: 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.

### Selective point-and-click

For some interactive applications, it may be desirable to only include certain point-and-click items. For example, if somebody wanted to create an application which played audio or video starting from a particular note, it would be awkward if clicking on the note produced the point-and-click location for an accidental or slur which occurred over that note.

This may be controlled by indicating which events to include:

• Hard-coded in the ‘.ly’ file:
\pointAndClickTypes #'note-event
\relative c' {
c2\f( f)
}


or

#(ly:set-option 'point-and-click 'note-event)
\relative c' {
c2\f( f)
}

• Command-line:
lilypond -dpoint-and-click=note-event   example.ly


Multiple events can be included:

• Hard-coded in the ‘.ly’ file:
\pointAndClickTypes #'(note-event dynamic-event)
\relative c' {
c2\f( f)
}


or

#(ly:set-option 'point-and-click '(note-event dynamic-event))
\relative c' {
c2\f( f)
}

• Command-line:  lilypond \ -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \ example.ly 

## 4.2 Text editor support

There is support for different text editors for LilyPond.

### Emacs mode

Emacs has a ‘lilypond-mode’, which provides keyword autocompletion, indentation, LilyPond specific parenthesis matching and syntax coloring, handy compile short-cuts and reading LilyPond manuals using Info. If ‘lilypond-mode’ is not installed on your platform, see below.

An Emacs mode for entering music and running LilyPond is contained in the source archive in the ‘elisp’ directory. Do make install to install it to elispdir. The file ‘lilypond-init.el’ should be placed to load-path/site-start.d/’ or appended to your ‘~/.emacs’ or ‘~/.emacs.el’.

(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))


### Vim mode

For Vim, a filetype plugin, indent mode, and syntax-highlighting mode are available to use with LilyPond. To enable all of these features, create (or modify) your ‘$HOME/.vimrc’ to contain these three lines, in order: filetype off set runtimepath+=/usr/local/share/lilypond/current/vim/ filetype on syntax on  If LilyPond is not installed in the ‘/usr/local/’ directory, change the path appropriately. This topic is discussed in Other sources of information. ### Other editors Other editors (both text and graphical) support LilyPond, but their special configuration files are not distributed with LilyPond. Consult their documentation for more information. Such editors are listed in Easier editing. ## 4.3 Converting from other formats 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 website for more details. These are separate programs from lilypond itself, and are run on the command line; see Command-line usage for more information. If you have MacOS 10.3 or 10.4 and you have trouble running some of these scripts, e.g. convert-ly, see MacOS X. #### Known issues and warnings 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. ### 4.3.1 Invoking midi2ly midi2ly translates a Type 1 MIDI file to a LilyPond source file. 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. midi2ly converts tracks into Staff and channels into Voice contexts. Relative mode is used for pitches, durations are only written when necessary. It is possible to record a MIDI file using a digital keyboard, and then convert it to ‘.ly’. However, human players are not rhythmically exact enough to make a MIDI to LY conversion trivial. When invoked with quantizing (‘-s’ and ‘-d’ options) midi2ly tries to compensate for these timing errors, but is not very good at this. It is therefore not recommended to use midi2ly for human-generated midi files. It is invoked from the command-line as follows, midi2ly [option]… midi-file  Note that by ‘command-line’, we mean the command line of the operating system. See Converting from other formats, for more information about this. The following options are supported by midi2ly. -a, --absolute-pitches Print absolute pitches. -d, --duration-quant=DUR Quantize note durations on DUR. -e, --explicit-durations Print explicit durations. -h, --help Show summary of usage. -k, --key=acc[:minor] Set default key. acc > 0 sets number of sharps; acc < 0 sets number of flats. A minor key is indicated by :1. -o, --output=file Write output to file. -s, --start-quant=DUR Quantize note starts on DUR. -t, --allow-tuplet=DUR*NUM/DEN Allow tuplet durations DUR*NUM/DEN. -v, --verbose Be verbose. -V, --version Print version number. -w, --warranty Show warranty and copyright. -x, --text-lyrics Treat every text as a lyric. #### Known issues and warnings 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. ### 4.3.2 Invoking musicxml2ly MusicXML is an XML dialect for representing music notation. musicxml2ly extracts the notes, articulations, score structure, lyrics, etc. from part-wise MusicXML files, and writes them to a ‘.ly’ file. It is invoked from the command-line. It is invoked from the command-line as follows, musicxml2ly [option]… xml-file  Note that by ‘command-line’, we mean the command line of the operating system. See Converting from other formats, for more information about this. If the given filename is ‘-’, musicxml2ly reads input from the command line. The following options are supported by musicxml2ly: -a, --absolute convert pitches in absolute mode. -h, --help print usage and option summary. -l, --language=LANG use LANG for pitch names, e.g. ’deutsch’ for note names in German. --loglevel=loglevel Set the output verbosity to loglevel. Possible values are NONE, ERROR, WARNING, PROGRESS (default) and DEBUG. --lxml use the lxml.etree Python package for XML-parsing; uses less memory and cpu time. -m, --midi activate midi-block. -nd, --no-articulation-directions do not convert directions (^, _ or -) for articulations, dynamics, etc. --no-beaming do not convert beaming information, use LilyPond’s automatic beaming instead. -o, --output=file set output filename to file. If file is ‘-’, the output will be printed on stdout. If not given, xml-file.ly’ will be used. -r, --relative convert pitches in relative mode (default). -v, --verbose be verbose. --version print version information. -z, --compressed input file is a zip-compressed MusicXML file. ### 4.3.3 Invoking abc2ly Note: This program is not supported, and may be remove from future versions of LilyPond. ABC is a fairly simple ASCII based format. It is described at the ABC site: abc2ly translates from ABC to LilyPond. It is invoked as follows: abc2ly [option]… abc-file  The following options are supported by abc2ly: -b, --beams=None preserve ABC’s notion of beams -h, --help this help -o, --output=file set output filename to file. -s, --strict be strict about success --version print version information. There is a rudimentary facility for adding LilyPond code to the ABC source file. If you say: %%LY voices \set autoBeaming = ##f  This will cause the text following the keyword ‘voices’ to be inserted into the current voice of the LilyPond output file. Similarly, %%LY slyrics more words  will cause the text following the ‘slyrics’ keyword to be inserted into the current line of lyrics. #### Known issues and warnings The ABC standard is not very ‘standard’. For extended features (e.g., polyphonic music) different conventions exist. Multiple tunes in one file cannot be converted. ABC synchronizes words and notes at the beginning of a line; abc2ly does not. abc2ly ignores the ABC beaming. ### 4.3.4 Invoking etf2ly Note: This program is not supported, and may be remove from future versions of LilyPond. ETF (Enigma Transport Format) is a format used by Coda Music Technology’s Finale product. etf2ly will convert part of an ETF file to a ready-to-use LilyPond file. It is invoked from the command-line as follows. etf2ly [option]… etf-file  Note that by ‘command-line’, we mean the command line of the operating system. See Converting from other formats, for more information about this. The following options are supported by etf2ly: -h, --help this help -o, --output=FILE set output filename to FILE --version version information #### Known issues and warnings The list of articulation scripts is incomplete. Empty measures confuse etf2ly. Sequences of grace notes are ended improperly. ### 4.3.5 Other formats LilyPond itself does not come with support for any other formats, but some external tools can also generate LilyPond files. These are listed in Easier editing. ## 4.4 LilyPond output in other programs This section shows methods to integrate text and music, different than the automated method with lilypond-book. ### Many quotes from a large score If you need to quote many fragments from a large score, you can also use the clip systems feature, see Extracting fragments of music. ### Inserting LilyPond output into OpenOffice and LibreOffice LilyPond notation can be added to OpenOffice.org and LibreOffice with OOoLilyPond. ### Inserting LilyPond output into other programs To insert LilyPond output in other programs, use lilypond instead of lilypond-book. 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 ‘PNG’, ‘EPS’, or ‘PDF’ formats. To reduce the white space around your LilyPond score, use the following options \paper{ indent=0\mm line-width=120\mm oddFooterMarkup=##f oddHeaderMarkup=##f bookTitleMarkup = ##f scoreTitleMarkup = ##f } { c1 }  To produce useful image files: EPS lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly PNG lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly A transparent PNG lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \ -dpixmap-format=pngalpha --png myfile.ly  ## 4.5 Independent includes Some people have written large (and useful!) code that can be shared between projects. This code might eventually make its way into LilyPond itself, but until that happens, you must download and \include them manually. ### 4.5.1 MIDI articulation LilyPond can be used to produce MIDI output, for “proof-hearing” what has been written. However, only dynamics, explicit tempo markings, and the notes and durations themselves are produced in the output. The articulate project is one attempt to get more of the information in the score into MIDI. It works by shortening notes not under slurs, to ‘articulate’ the notes. The amount of shortening depends on any articulation markings attached to a note: staccato halves the note value, tenuto gives a note its full duration, and so on. The script also realises trills and turns, and could be extended to expand other ornaments such as mordents. http://www.nicta.com.au/people/chubbp/articulate  #### Known issues and warnings Its main limitation is that it can only affect things it knows about: anything that is merely textual markup (instead of a note property) is still ignored. # 5. Suggestions for writing files Now you’re ready to begin writing larger LilyPond input files – not just the little examples in the tutorial, but whole pieces. But how should you go about doing it? As long as LilyPond can understand your input files and produce the output that you want, it doesn’t matter what your input files look like. However, there are a few other things to consider when writing LilyPond input files. • What if you make a mistake? The structure of a LilyPond file can make certain errors easier (or harder) to find. • What if you want to share your input files with somebody else? In fact, what if you want to alter your own input files in a few years? Some LilyPond input files are understandable at first glance; others may leave you scratching your head for an hour. • What if you want to upgrade your LilyPond file for use with a later version of LilyPond? The input syntax changes occasionally as LilyPond improves. Most changes can be done automatically with convert-ly, but some changes might require manual assistance. LilyPond input files can be structured in order to be easier (or harder) to update. ## 5.1 General suggestions Here are a few suggestions that can help you to avoid or fix problems: • Include \version numbers in every file. Note that all templates contain \version information. We highly recommend that you always include the \version, no matter how small your file is. Speaking from personal experience, it’s quite frustrating to try to remember which version of LilyPond you were using a few years ago. convert-ly requires you to declare which version of LilyPond you used. • Include checks: Bar and bar number checks, Octave checks. If you include checks every so often, then if you make a mistake, you can pinpoint it quicker. How often is ‘every so often’? It depends on the complexity of the music. For very simple music, perhaps just once or twice. For very complex music, perhaps every bar. • One bar per line of text. If there is anything complicated, either in the music itself or in the output you desire, it’s often good to write only one bar per line. Saving screen space by cramming eight bars per line just isn’t worth it if you have to ‘debug’ your input files. • Comment your input files. Use either bar numbers (every so often) or references to musical themes (‘second theme in violins,’ ‘fourth variation,’ etc.). You may not need comments when you’re writing the piece for the first time, but if you want to go back to change something two or three years later, or if you pass the source over to a friend, it will be much more challenging to determine your intentions or how your file is structured if you didn’t comment the file. • Indent your braces. A lot of problems are caused by an imbalance in the number of { and }. • Explicitly add durations at the beginnings of sections and variables. If you specify c4 d e at the beginning of a phrase (instead of just c d e) you can save yourself some problems if you rearrange your music later. • Separate tweaks from music definitions. See Saving typing with variables and functions, and Style sheets. ## 5.2 Typesetting existing music If you are entering music from an existing score (i.e., typesetting a piece of existing sheet music), • Enter the manuscript (the physical copy of the music) into LilyPond one system at a time (but still only one bar per line of text), and check each system when you finish it. You may use the showLastLength or showFirstLength properties to speed up processing – see Skipping corrected music. • Define mBreak = { \break } and insert \mBreak in the input file whenever the manuscript has a line break. This makes it much easier to compare the LilyPond music to the original music. When you are finished proofreading your score, you may define mBreak = { } to remove all those line breaks. This will allow LilyPond to place line breaks wherever it feels are best. • When entering a part for a transposing instrument into a variable, it is recommended that the notes are wrapped in \transpose c natural-pitch {…}  (where natural-pitch is the open pitch of the instrument) so that the music in the variable is effectively in C. You can transpose it back again when the variable is used, if required, but you might not want to (e.g., when printing a score in concert pitch, converting a trombone part from treble to bass clef, etc.) Mistakes in transpositions are less likely if all the music in variables is at a consistent pitch. Also, only ever transpose to/from C. That means that the only other keys you will use are the natural pitches of the instruments - bes for a B-flat trumpet, aes for an A-flat clarinet, etc. ## 5.3 Large projects When working on a large project, having a clear structure to your lilypond input files becomes vital. • Use a variable for each voice, with a minimum of structure inside the definition. The structure of the \score section is the most likely thing to change; the violin definition is extremely unlikely to change in a new version of LilyPond. violin = \relative c'' { g4 c'8. e16 } … \score { \new GrandStaff { \new Staff { \violin } } }  • Separate tweaks from music definitions. This point was made previously, but for large projects it is absolutely vital. We might need to change the definition of fthenp, but then we only need to do this once, and we can still avoid touching anything inside violin. fthenp = _\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p } violin = \relative c'' { g4\fthenp c'8. e16 }  ## 5.4 Troubleshooting Sooner or later, you will write a file that LilyPond cannot compile. The messages that LilyPond gives may help you find the error, but in many cases you need to do some investigation to determine the source of the problem. The most powerful tools for this purpose are the single line comment (indicated by %) and the block comment (indicated by %{…%}). If you don’t know where a problem is, start commenting out huge portions of your input file. After you comment out a section, try compiling the file again. If it works, then the problem must exist in the portion you just commented. If it doesn’t work, then keep on commenting out material until you have something that works. In an extreme case, you might end up with only \score { << % \melody % \harmony % \bass >> \layout{} }  (in other words, a file without any music) If that happens, don’t give up. Uncomment a bit – say, the bass part – and see if it works. If it doesn’t work, then comment out all of the bass music (but leave \bass in the \score uncommented. bass = \relative c' { %{ c4 c c c d d d d %} }  Now start slowly uncommenting more and more of the bass part until you find the problem line. Another very useful debugging technique is constructing Tiny examples. ## 5.5 Make and Makefiles Pretty well all the platforms Lilypond can run on support a software facility called make. This software reads a special file called a Makefile that defines what files depend on what others and what commands you need to give the operating system to produce one file from another. For example the makefile would spell out how to produce ‘ballad.pdf’ and ‘ballad.midi’ from ‘ballad.ly’ by running Lilypond. There are times when it is a good idea to create a Makefile for your project, either for your own convenience or as a courtesy to others who might have access to your source files. This is true for very large projects with many included files and different output options (e.g. full score, parts, conductor’s score, piano reduction, etc.), or for projects that require difficult commands to build them (such as lilypond-book projects). Makefiles vary greatly in complexity and flexibility, according to the needs and skills of the authors. The program GNU Make comes installed on GNU/Linux distributions and on MacOS X, and it is also available for Windows. See the GNU Make Manual for full details on using make, as what follows here gives only a glimpse of what it can do. The commands to define rules in a makefile differ according to platform; for instance the various forms of GNU/Linux and MacOS use bash, while Windows uses cmd. Note that on MacOS X, you need to configure the system to use the command-line interpreter. Here are some example makefiles, with versions for both GNU/Linux/MacOS and Windows. The first example is for an orchestral work in four movements with a directory structure as follows: Symphony/ |-- MIDI/ |-- Makefile |-- Notes/ | |-- cello.ily | |-- figures.ily | |-- horn.ily | |-- oboe.ily | |-- trioString.ily | |-- viola.ily | |-- violinOne.ily | -- violinTwo.ily |-- PDF/ |-- Parts/ | |-- symphony-cello.ly | |-- symphony-horn.ly | |-- symphony-oboes.ly | |-- symphony-viola.ly | |-- symphony-violinOne.ly | -- symphony-violinTwo.ly |-- Scores/ | |-- symphony.ly | |-- symphonyI.ly | |-- symphonyII.ly | |-- symphonyIII.ly | -- symphonyIV.ly -- symphonyDefs.ily  The ‘.ly’ files in the ‘Scores’ and ‘Parts’ directories get their notes from ‘.ily’ files in the ‘Notes’ directory: %%% top of file "symphony-cello.ly" \include ../symphonyDefs.ily \include ../Notes/cello.ily  The makefile will have targets of score (entire piece in full score), movements (individual movements in full score), and parts (individual parts for performers). There is also a target archive that will create a tarball of the source files, suitable for sharing via web or email. Here is the makefile for GNU/Linux or MacOS X. It should be saved with the name Makefile in the top directory of the project: Note: When a target or pattern rule is defined, the subsequent lines must begin with tabs, not spaces. # the name stem of the output files piece = symphony # determine how many processors are present CPU_CORES=cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "// # The command to run lilypond LILY_CMD = lilypond -ddelete-intermediate-files \ -dno-point-and-click -djob-count=$(CPU_CORES)

# The suffixes used in this Makefile.
.SUFFIXES: .ly .ily .pdf .midi

# Input and output files are searched in the directories listed in
# the VPATH variable.  All of them are subdirectories of the current
# directory (given by the GNU make variable CURDIR').
VPATH = \
$(CURDIR)/Scores \$(CURDIR)/PDF \
$(CURDIR)/Parts \$(CURDIR)/Notes

# The pattern rule to create PDF and MIDI files from a LY input file.
# The .pdf output files are put into the PDF' subdirectory, and the
# .midi files go into the MIDI' subdirectory.
%.pdf %.midi: %.ly
$(LILY_CMD)$<; \           # this line begins with a tab
if test -f "$*.pdf"; then \ mv "$*.pdf" PDF/; \
fi; \
if test -f "$*.midi"; then \ mv "$*.midi" MIDI/; \
fi

notes = \
cello.ily \
horn.ily \
oboe.ily \
viola.ily \
violinOne.ily \
violinTwo.ily

# The dependencies of the movements.
$(piece)I.pdf:$(piece)I.ly $(notes)$(piece)II.pdf: $(piece)II.ly$(notes)
$(piece)III.pdf:$(piece)III.ly $(notes)$(piece)IV.pdf: $(piece)IV.ly$(notes)

# The dependencies of the full score.
$(piece).pdf:$(piece).ly $(notes) # The dependencies of the parts.$(piece)-cello.pdf: $(piece)-cello.ly cello.ily$(piece)-horn.pdf: $(piece)-horn.ly horn.ily$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily$(piece)-viola.pdf: $(piece)-viola.ly viola.ily$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily # Type make score' to generate the full score of all four # movements as one file. .PHONY: score score:$(piece).pdf

# Type make parts' to generate all parts.
# Type make foo.pdf' to generate the part for instrument foo'.
# Example: make symphony-cello.pdf'.
.PHONY: parts
parts: $(piece)-cello.pdf \$(piece)-violinOne.pdf \
$(piece)-violinTwo.pdf \$(piece)-viola.pdf \
$(piece)-oboes.pdf \$(piece)-horn.pdf

# Type make movements' to generate files for the
# four movements separately.
.PHONY: movements
movements: $(piece)I.pdf \$(piece)II.pdf \
$(piece)III.pdf \$(piece)IV.pdf

all: score parts movements

archive:
tar -cvvf stamitz.tar \       # this line begins with a tab
--exclude=*pdf --exclude=*~ \
--exclude=*midi --exclude=*.tar \
../Stamitz/*


There are special complications on the Windows platform. After downloading and installing GNU Make for Windows, you must set the correct path in the system’s environment variables so that the DOS shell can find the Make program. To do this, right-click on "My Computer," then choose Properties and Advanced. Click Environment Variables, and then in the System Variables pane, highlight Path, click edit, and add the path to the GNU Make executable file, which will look something like this:

C:\Program Files\GnuWin32\bin


The makefile itself has to be altered to handle different shell commands and to deal with spaces that are present in some default system directories. The archive target is eliminated since Windows does not have the tar command, and Windows also has a different default extension for midi files.

## WINDOWS VERSION
##
piece = symphony
LILY_CMD = lilypond -ddelete-intermediate-files \
-dno-point-and-click \
-djob-count=$(NUMBER_OF_PROCESSORS) #get the 8.3 name of CURDIR (workaround for spaces in PATH) workdir =$(shell for /f "tokens=*" %%b in ("$(CURDIR)") \ do @echo %%~sb) .SUFFIXES: .ly .ily .pdf .mid VPATH = \$(workdir)/Scores \
$(workdir)/PDF \$(workdir)/Parts \
$(workdir)/Notes %.pdf %.mid: %.ly$(LILY_CMD) $< # this line begins with a tab if exist "$*.pdf"  move /Y "$*.pdf" PDF/ # begin with tab if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab notes = \ cello.ily \ figures.ily \ horn.ily \ oboe.ily \ trioString.ily \ viola.ily \ violinOne.ily \ violinTwo.ily$(piece)I.pdf: $(piece)I.ly$(notes)
$(piece)II.pdf:$(piece)II.ly $(notes)$(piece)III.pdf: $(piece)III.ly$(notes)
$(piece)IV.pdf:$(piece)IV.ly $(notes)$(piece).pdf: $(piece).ly$(notes)

$(piece)-cello.pdf:$(piece)-cello.ly cello.ily
$(piece)-horn.pdf:$(piece)-horn.ly horn.ily
$(piece)-oboes.pdf:$(piece)-oboes.ly oboe.ily
$(piece)-viola.pdf:$(piece)-viola.ly viola.ily
$(piece)-violinOne.pdf:$(piece)-violinOne.ly violinOne.ily
$(piece)-violinTwo.pdf:$(piece)-violinTwo.ly violinTwo.ily

.PHONY: score
score: $(piece).pdf .PHONY: parts parts:$(piece)-cello.pdf \
$(piece)-violinOne.pdf \$(piece)-violinTwo.pdf \
$(piece)-viola.pdf \$(piece)-oboes.pdf \
$(piece)-horn.pdf .PHONY: movements movements:$(piece)I.pdf \
$(piece)II.pdf \$(piece)III.pdf \
$(piece)IV.pdf all: score parts movements  The next Makefile is for a lilypond-book document done in LaTeX. This project has an index, which requires that the latex command be run twice to update links. Output files are all stored in the out directory for .pdf output and in the htmlout directory for the html output. SHELL=/bin/sh FILE=myproject OUTDIR=out WEBDIR=htmlout VIEWER=acroread BROWSER=firefox LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex PDF=cd$(OUTDIR) && pdflatex $(FILE) HTML=cd$(WEBDIR) && latex2html $(FILE) INDEX=cd$(OUTDIR) && makeindex $(FILE) PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &

all: pdf web keep

pdf:
$(LILYBOOK_PDF) # begin with tab$(PDF)           # begin with tab
$(INDEX) # begin with tab$(PDF)           # begin with tab
$(PREVIEW) # begin with tab web:$(LILYBOOK_HTML) # begin with tab
$(HTML) # begin with tab cp -R$(WEBDIR)/$(FILE)/ ./ # begin with tab$(BROWSER) $(FILE)/$(FILE).html &  # begin with tab

keep: pdf
cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab clean: rm -rf$(OUTDIR) # begin with tab

web-clean:
rm -rf \$(WEBDIR) # begin with tab

archive:
tar -cvvf myproject.tar \ # begin this line with tab
--exclude=out/* \
--exclude=htmlout/* \
--exclude=myproject/* \
--exclude=*midi \
--exclude=*pdf \
--exclude=*~ \
../MyProject/*


TODO: make this thing work on Windows

The previous makefile does not work on Windows. An alternative for Windows users would be to create a simple batch file containing the build commands. This will not keep track of dependencies the way a makefile does, but it at least reduces the build process to a single command. Save the following code as build.bat or build.cmd. The batch file can be run at the DOS prompt or by simply double-clicking its icon.

lilypond-book --output=out --pdf myproject.lytex
cd out
pdflatex myproject
makeindex myproject
pdflatex myproject
cd ..
copy out\myproject.pdf MyProject.pdf


This manual: Command-line usage, Running lilypond-book

# A. GNU Free Documentation License

Version 1.3, 3 November 2008

 Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 
1. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

2. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document 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, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

The “publisher” means any person or entity that distributes copies of the Document to the public.

A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

3. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

4. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

5. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

1. 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.
2. 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 fewer than five), unless they release you from this requirement.
3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
4. Preserve all the copyright notices of the Document.
6. 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.
7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
8. Include an unaltered copy of this License.
9. Preserve the section Entitled “History”, Preserve 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.
10. 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.
11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
12. 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.
13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
15. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

6. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

7. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

8. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

9. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

10. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

11. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

12. RELICENSING

“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License''. 

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

  with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list. 

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

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.

# B. LilyPond index

Jump to: \   A   B   C   D   E   F   H   I   L   M   O   P   S   T   U   V   W   X
Jump to: \   A   B   C   D   E   F   H   I   L   M   O   P   S   T   U   V   W   X

# Footnotes

[1] The status of GUILE is not reset after processing a .ly` file, so be careful not to change any system defaults from within Scheme.

[2] At least, this is possible in any LilyPond file which does not contain scheme. If there is scheme in the file, then the LilyPond file contains a Turing-complete language, and we run into problems with the famous “Halting Problem” in computer science.

[3] This tutorial is processed with Texinfo, so the example gives slightly different results in layout.

[4] Note that PDFLaTeX and LaTeX may not be both usable to compile any LaTeX document, that is why we explain the two ways.

This document was generated by gub on March 17, 2014 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[]
[ << ] FastBack Beginning of this chapter or previous chapter 1
[]
[Top] Top Cover (top) of document
[Index] Index Index
[]
[ >> ] FastForward Next chapter 2
[]
[]
[ < ] Back Previous section in reading order 1.2.2
[]
[ Up ] Up Up section 1.2
[]
[ > ] Forward Next section in reading order 1.2.4

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
• 1.1 Subsection One-One
• ...
• 1.2 Subsection One-Two
• 1.2.1 Subsubsection One-Two-One
• 1.2.2 Subsubsection One-Two-Two
• 1.2.3 Subsubsection One-Two-Three     <== Current Position
• 1.2.4 Subsubsection One-Two-Four
• 1.3 Subsection One-Three
• ...
• 1.4 Subsection One-Four

Other languages: deutsch, español, français, magyar, italiano, 日本語.