Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.15.18"
@node Running lilypond
This chapter details the technicalities of running LilyPond.
@menu
-* Normal usage::
-* Command-line usage::
-* Error messages::
-* Common errors::
-* Point and click::
-* Text editor support::
+* Normal usage::
+* Command-line usage::
+* Error messages::
+* Common errors::
@end menu
@section Normal usage
Most users run LilyPond through a GUI; if you have not done so
-already, read @rlearning{Introduction}. If you use an alternate
+already, please read the @rlearning{Tutorial}. If you use an alternate
editor to write lilypond files, see the documentation for that
program.
Windows users might be more familiar with the terms @q{DOS shell} or
@q{command shell}. MacOS@tie{}X users might be more familiar with the terms
@q{terminal} or @q{console}. Some additional setup is required
-for MacOS@tie{}X users; please see @rgeneral{MacOS X}.
+for MacOS@tie{}X users; please see @rweb{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.
@menu
-* Invoking lilypond::
-* Command line options for lilypond::
-* Environment variables::
+* Invoking lilypond::
+* Command line options for lilypond::
+* Environment variables::
+* LilyPond in chroot jail::
@end menu
@node Invoking lilypond
@var{base}@file{-cello-1.pdf}.
-@node Command line options for lilypond
-@unnumberedsubsec Command line options for @command{lilypond}
+@unnumberedsubsubsec Standard shell commands
-@cindex Invoking @command{lilypond}
-@cindex command line options for @command{lilypond}
-@cindex options, command line
-@cindex switches
+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:
-The following options are supported:
+@itemize
-@table @code
+@item
+@code{lilypond file.ly 1>stdout.log} to redirect normal output
-@item -e,--evaluate=@var{expr}
-Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
-Multiple @code{-e} options may be given, they will be evaluated
-sequentially.
+@item
+@code{lilypond file.ly 2>stderr.log} to redirect error messages
-The expression will be evaluated in the @code{guile-user} module, so
-if you want to use definitions in @var{expr}, use
+@item
+@code{lilypond file.ly &>all.log} to redirect all output
-@example
-lilypond -e '(define-public a 42)'
-@end example
-
-@noindent
-on the command-line, and include
+@end itemize
-@example
-#(use-modules (guile-user))
-@end example
+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.
-@noindent
-at the top of the @code{.ly} file.
-@item -f,--format=@var{format}
-which formats should be written. Choices for @code{format} are
-@code{svg}, @code{ps}, @code{pdf}, and @code{png}.
+@node Command line options for lilypond
+@unnumberedsubsec Command line options for @command{lilypond}
-Example: @code{lilypond -fpng @var{filename}.ly}
+@cindex Invoking @command{lilypond}
+@cindex command line options for @command{lilypond}
+@cindex options, command line
+@cindex switches
+The following options are supported:
+@table @code
@item -d,--define-default=@var{var}=@var{val}
This sets the internal program option @var{var} to the Scheme value
@noindent
is the same as
@example
--dpoint-and-click='#f'
+-dpoint-and-click=#f
@end example
-Here are a few interesting options.
+The following options are supported:
@cindex help, command line
-@table @samp
+@table @code
+
@item help
-Running @code{lilypond -dhelp} will print all of the @code{-d} options
+Running @code{lilypond -dhelp} will print all of the @option{-d} options
available.
@cindex paper-size, command line
Do not trust the @code{.ly} input.
When LilyPond formatting is available through a web server, either the
-@code{--safe} or the @code{--jail} option @b{MUST} be passed. The
-@code{--safe} option will prevent inline Scheme code from wreaking
+@option{--safe} or the @option{--jail} option @b{MUST} be passed. The
+@option{--safe} option will prevent inline Scheme code from wreaking
havoc, for example
@quotation
@verbatim
#(system "rm -rf /")
{
- c4^#(ly:export (ly:gulp-file "/etc/passwd"))
+ c4^$(ly:gulp-file "/etc/passwd")
}
@end verbatim
@end quotation
-The @code{-dsafe} option works by evaluating in-line Scheme
+The @option{-dsafe} option works by evaluating in-line Scheme
expressions in a special safe module. This safe module is derived from
GUILE @file{safe-r5rs} module, but adds a number of functions of the
-LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
+LilyPond API. These functions are listed in @file{scm/safe-lily.scm}.
In addition, safe mode disallows @code{\include} directives and
disables the use of backslashes in @TeX{} strings.
-In safe mode, it is not possible to import LilyPond variables
-into Scheme.
+In safe mode, it is not possible to import LilyPond variables into
+Scheme.
-@code{-dsafe} does @emph{not} 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.
+@option{-dsafe} does @emph{not} 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.
-The safe mode will prevent many useful LilyPond snippets from being
-compiled. The @code{--jail} is a more secure alternative, but
+Safe mode will prevent many useful LilyPond snippets from being
+compiled. The @option{--jail} is a more secure alternative, but
requires more work to set up.
@cindex output format, setting
+
@item backend
-the output format to use for the back-end. Choices for @code{format} are
+the output format to use for the backend. Choices for @code{format}
+are:
+
@table @code
@item ps
+
@cindex PostScript output
- for PostScript.
- 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.
+for PostScript.
+
+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.
@item eps
-@cindex Postscript, encapulated
+@cindex Postscript, encapsulated
@cindex EPS (Encapsulated PostScript)
- for encapsulated PostScript. This dumps every page (system) as a separate
-@file{EPS} file, without fonts, and as one collated @file{EPS} file with
-all pages (systems) including fonts.
+for encapsulated PostScript. This dumps every page (system) as a
+separate @file{EPS} file, without fonts, and as one collated @file{EPS}
+file with all pages (systems) including fonts.
This mode is used by default by @command{lilypond-book}.
@cindex SVG (Scalable Vector Graphics)
- for SVG (Scalable Vector Graphics).
+for 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
- @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
- @file{~/.fonts/}. The SVG output should be compatible with any
- SVG editor or user agent.
+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
+@file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}. The
+SVG output should be compatible with any SVG editor or user agent.
@item scm
@cindex Scheme dump
+@cindex output, Scheme dump
- for a dump of the raw, internal Scheme-based drawing commands.
+for a dump of the raw, internal Scheme-based drawing commands.
@item null
- do not output a printed score; has the same effect as @code{-dno-print-pages}.
+do not output a printed score; has the same effect as
+@option{-dno-print-pages}.
+
@end table
Example: @code{lilypond -dbackend=svg @var{filename}.ly}
@item preview
+
@cindex preview, command line
-Generate an output file containing the titles and the first system
+
+This option is supported by all backends; @code{pdf}, @code{png},
+@code{ps}, @code{eps} and @code{svg}, but not @code{scm} and generates
+an output file containing the titles and the first system of music. If
+@code{\bookpart} blocks are used, the titles and first system of every
+@code{\bookpart} will appear in the output.
+
+An additional file in the form @code{myFile.preview.extension} is
+generated, to avoid this use the additional @option{-dprint-pages} or
+@option{-dno-print-pages} options according to your requirements.
+
+@item gui
+Runs silently and redirect all output to a log file.
+
+Note to Windows users: By default @code{lilypond.exe} outputs all
+progress information to the command window, @code{lilypond-windows.exe}
+does not and returns a prompt, with no progress information, immediately
+at the command line. The @option{-dgui} option can be used in this case
+to redirect output to a log file.
@item print-pages
-Generate the full pages, the default. @code{-dno-print-pages} is
-useful in combination with @code{-dpreview}.
+Generate the full pages, the default. @option{-dno-print-pages} is
+useful in combination with @option{-dpreview}.
@end table
+@cindex Scheme, expression evaluation
+@cindex expression evaluation, Scheme
+@item -e,--evaluate=@var{expr}
+Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
+Multiple @option{-e} options may be given, they will be evaluated
+sequentially.
-@item -h,--help
-Show a summary of usage.
+The expression will be evaluated in the @code{guile-user} module, so
+if you want to use definitions in @var{expr}, use
-@item -H,--header=@var{FIELD}
-Dump a header field to file @file{BASENAME.@var{FIELD}}.
+@example
+lilypond -e '(define-public a 42)'
+@end example
-@item --include, -I=@var{directory}
-Add @var{directory} to the search path for input files.
-@cindex file searching
-@cindex search path
+@noindent
+on the command-line, and include
-@item -i,--init=@var{file}
-Set init file to @var{file} (default: @file{init.ly}).
+@example
+#(use-modules (guile-user))
+@end example
+
+@noindent
+at the top of the @code{.ly} file.
-@item -o,--output=@var{FILE}
-Set the default output file to @var{FILE}. The appropriate
-suffix will be added (e.g. @code{.pdf} for pdf)
+@warning{Windows users must use double quotes instead of single quotes.}
-@cindex PostScript output
+@cindex output, format
+@cindex format, output
-@item --ps
-Generate PostScript.
+@item -f,--format=@var{format}
+which formats should be written. Choices for @code{format} are
+@code{ps}, @code{pdf}, and @code{png}.
-@cindex Portable Network Graphics (PNG) output
+Example: @code{lilypond -fpng @var{filename}.ly}
-@item --png
-Generate pictures of each page, in PNG format. This implies
-@code{--ps}. The resolution in DPI of the image may be set with
-@example
--dresolution=110
-@end example
+@item -h,--help
+Show a summary of usage.
-@cindex Portable Document Format (PDF) output
+@item -H,--header=@var{FIELD}
+Dump a header field to file @file{BASENAME.@var{FIELD}}.
-@item --pdf
-Generate PDF. This implies @code{--ps}.
+@item -i,--init=@var{file}
+Set init file to @var{file} (default: @file{init.ly}).
+
+@cindex file searching
+@cindex search path
+
+@item -I, --include=@var{directory}
+Add @var{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.
+@cindex chroot jail, running inside
@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
Run @command{lilypond} in a chroot jail.
-The @code{--jail} option provides a more flexible alternative to
-@code{--safe} when LilyPond formatting is available through a web
+The @option{--jail} option provides a more flexible alternative to
+@option{--safe} when LilyPond formatting is available through a web
server or whenever LilyPond executes externally provided
sources.
-The @code{--jail} option works by changing the root of @command{lilypond} to
-@var{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 @var{dir}. This setup guarantees that it is not
-possible (at least in theory) to escape from the jail. Note that for
-@code{--jail} to work @command{lilypond} must be run as root, which is usually
-accomplished in a safe way using @command{sudo}.
+The @option{--jail} option works by changing the root of
+@command{lilypond} to @var{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 @var{dir}. This setup
+guarantees that it is not possible (at least in theory) to escape from
+the jail. Note that for @option{--jail} to work @command{lilypond} must
+be run as root, which is usually accomplished in a safe way using
+@command{sudo}.
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
@emph{inside the jail}. A typical setup comprises the following items:
@table @asis
+
@item Setting up a separate filesystem
A separate filesystem should be created for LilyPond, so that it can be
mounted with safe options such as @code{noexec}, @code{nodev}, and
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., @file{/usr/share/lilypond})
-should be copied.
+(e.g., @file{/usr/share/lilypond}) should be copied.
If problems arise, the simplest way to trace them down is to run
LilyPond using @command{strace}, which will allow you to determine which
files are missing.
@item Running LilyPond
-In a jail mounted with @code{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 already mentioned, it must be also run
-with superuser privileges (which, of course, it will lose immediately),
-possibly using @command{sudo}. It is a good idea to limit the number of
-seconds of CPU time LilyPond can use (e.g., using @command{ulimit
--t}), and, if your operating system supports it, the amount of memory
-that can be allocated.
+In a jail mounted with @code{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 already mentioned, it must be
+also run with superuser privileges (which, of course, it will lose
+immediately), possibly using @command{sudo}. It is a good idea to limit
+the number of seconds of CPU time LilyPond can use (e.g., using
+@command{ulimit@tie{}-t}), and, if your operating system supports it,
+the amount of memory that can be allocated.
+
+@end table
+
+@cindex loglevel
+@cindex output, verbosity
+
+@item -l,--loglevel=@var{LEVEL}
+Set the verbosity of the console output to @var{LEVEL}. Possible values
+are:
+
+@table @code
+
+@item NONE
+No output at all, not even error messages.
+
+@item ERROR
+Only error messages, no warnings or progress messages.
+
+@item WARN
+Warnings and error messages, no progress.
+
+@item BASIC_PROGRESS
+Basic progress messages (success), warnings and errors.
+
+@item PROGRESS
+All progress messages, warnings and errors.
+
+@item INFO (default)
+Progress messages, warnings, errors and further execution information.
+
+@item DEBUG
+All possible messages, including verbose debug output.
+
@end table
+@cindex directory, redirect output
+@cindex output, setting filename
+@cindex output, directory
+
+@item -o,--output=@var{FILE} or @var{FOLDER}
+Set the default output file to @var{FILE} or, if a folder with that name
+exists, direct the output to @var{FOLDER}, taking the file name from the
+input file. The appropriate suffix will be added (e.g. @code{.pdf} for
+pdf) in both cases.
+
+@cindex PS (Postscript), output
+@cindex Postscript (PS), output
+@cindex output, PS (Postscript)
+
+@item --ps
+Generate PostScript.
+
+@cindex PNG (Portable Network Graphics), output
+@cindex output, PNG (Portable Network Graphics)
+
+@item --png
+Generate pictures of each page, in PNG format. This implies
+@option{--ps}. The resolution in DPI of the image may be set with
+@example
+-dresolution=110
+@end example
+
+@cindex PDF (Portable Document Format), output
+@cindex output, PDF (Portable Document Format)
+
+@item --pdf
+Generate PDF. This implies @option{--ps}.
@item -v,--version
Show version information.
information.
@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
+Show the warranty with which GNU LilyPond comes. (It comes with
@strong{NO WARRANTY}!)
+
@end table
+
@node Environment variables
@unnumberedsubsec Environment variables
@item LANG
This selects the language for the warning messages.
+@item LILYPOND_LOGLEVEL
+The default loglevel. If LilyPond is called without an explicit loglevel (i.e.
+no @option{--loglevel} command line option), this value is used.
+
@item LILYPOND_GC_YIELD
-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}.
+A variable, as a percentage, that tunes memory management
+behavior. A higher values means the program uses more memory, a
+smaller value means more CPU time is used. The default value is
+@code{70}.
@end table
+@node LilyPond in chroot jail
+@unnumberedsubsec LilyPond in chroot jail
+
+Setting up the server to run LilyPond in a chroot jail is a complicated
+task. The steps are listed below. Examples in the steps are from
+Ubuntu Linux, and may require the use of @code{sudo} as appropriate.
+
+@itemize
+
+@item Install the necessary packages: LilyPond, GhostScript, and ImageMagick.
+
+@item Create a new user by the name of @code{lily}:
+
+@example
+adduser lily
+@end example
+
+@noindent
+This will create a new group for the @code{lily} user as well, and a
+home folder, @code{/home/lily}
+
+@item In the home folder of the @code{lily} user create a file to use as a
+separate filesystem:
+
+@example
+dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
+@end example
+
+@noindent
+This example creates a 200MB file for use as the jail filesystem.
+
+@item Create a loop device, make a file system and mount it, then create
+a folder that can be written by the @code{lily} user:
+
+@example
+mkdir /mnt/lilyloop
+losetup /dev/loop0 /home/lily/loopfile
+mkfs -t ext3 /dev/loop0 200000
+mount -t ext3 /dev/loop0 /mnt/lilyloop
+mkdir /mnt/lilyloop/lilyhome
+chown lily /mnt/lilyloop/lilyhome
+@end example
+
+@item In the configuration of the servers, the JAIL will be @code{/mnt/lilyloop}
+and the DIR will be @code{/lilyhome}.
+
+@item Create a big directory tree in the jail by copying the necessary files, as
+shown in the sample script below.
+
+You can use @code{sed} to create the necessary copy commands for a given
+executable:
+
+@example
+for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; \
+ 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
+@end example
+
+@end itemize
+
+@subheading Example script for 32-bit Ubuntu 8.04
+
+@example
+#!/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
+@end example
+
+@c " keep quote signs balanced for context-sensitive editors
+
@node Error messages
@section Error messages
@cindex call trace
@cindex Scheme error
Errors that occur while executing Scheme code are caught by the Scheme
-interpreter. If running with the verbose option (@code{-V} or
-@code{--verbose}) then a call trace of the offending
+interpreter. If running with the verbose option (@option{-V} or
+@option{--verbose}) then a call trace of the offending
function call is printed.
@item Programming error
@end table
@cindex errors, message format
-If warnings and errors can
-be linked to some part of the input file, then error messages have the
-following form
+If warnings and errors can be linked to some part of the input file,
+then error messages have the following form
@example
@var{filename}:@var{lineno}:@var{columnno}: @var{message}
@menu
-* Music runs off the page::
-* An extra staff appears::
-* Apparent error in ../ly/init.ly::
-* Error message Unbound variable %::
-* Error message FT_Get_Glyph_Name::
+* Music runs off the page::
+* An extra staff appears::
+* Apparent error in ../ly/init.ly::
+* Error message Unbound variable %::
+* Error message FT_Get_Glyph_Name::
+* Warning staff affinities should only decrease::
@end menu
@node Music runs off the page
@node An extra staff appears
@unnumberedsubsec An extra staff appears
-If contexts are not created explicitly with @code{\new} 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.
+If contexts are not created explicitly with @code{\new} or
+@code{\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.
@lilypond[quote,verbatim,relative=2]
\override Staff.NoteHead #'color = #red
@end lilypond
As a second example, if a @code{\relative} command is placed inside
-a @code{\repeat} command two staves result, the second offset from
+a @code{\repeat} command, two staves result, the second offset from
the first, because the @code{\repeat} command generates two
@code{\relative} blocks, which each implicitly create @code{Staff}
and @code{Voice} blocks.
@lilypond[quote,verbatim]
\repeat unfold 2 {
- \relative c' { c d e f }
+ \relative c' { c4 d e f }
}
@end lilypond
-The correct way is to reverse the @code{\repeat} and
-@code{\relative} commands, like this:
+Explicitly instantiating the @code{Voice} context fixes the
+problem:
@lilypond[quote,verbatim]
-\relative c' {
- \repeat unfold 2 { c d e f }
+\new Voice {
+ \repeat unfold 2 {
+ \relative c' { c4 d e f }
+ }
}
@end lilypond
@unnumberedsubsec Apparent error in @code{../ly/init.ly}
Various obscure error messages may appear about syntax errors in
-@code{../ly/init.ly} if the input file is not correctly formed,
+@file{../ly/init.ly} if the input file is not correctly formed,
for example, if it does not contain correctly
matched braces or quote signs.
this separation the brace is taken to be part of the syllable. It
is always advisable to ensure there is white space before and after
@emph{every} brace. For the importance of this when using lyrics,
-see @ruser{Lyrics explained}.
+see @ruser{Entering lyrics}.
This error message can also appear if a terminating quote sign,
(@code{"}), is omitted. In this case an accompanying error message
@unnumberedsubsec Error message Unbound variable %
This error message will appear at the bottom of the console
-output or log file together with a @qq{GUILE signalled an error ...}
+output or log file together with a @qq{GUILE signalled an error @dots{}}
message every time a Scheme routine is called which (invalidly)
contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
UTF-8 encoding. For details, see @ruser{Text encoding}.
-@node Point and click
-@section Point and click
-
-@cindex point and click
-
-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.
-
-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.
-
-To make this chain work, you should configure your PDF viewer to
-follow hyperlinks using the @file{lilypond-invoke-editor} script
-supplied with LilyPond.
-
-For Xpdf on UNIX, the following should be present in
-@file{xpdfrc}@footnote{On UNIX, this file is found either in
-@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
+@node Warning staff affinities should only decrease
+@unnumberedsubsec 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 @code{ChordName} context
+and a @code{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
@example
-urlCommand "lilypond-invoke-editor %s"
-@end example
-
-The program @file{lilypond-invoke-editor} is a small helper
-program. It will invoke an editor for the special @code{textedit}
-URIs, and run a web browser for others. It tests the environment
-variable @code{EDITOR} for the following patterns,
-
-@table @code
-@item emacs
- this will invoke
-@example
-emacsclient --no-wait +@var{line}:@var{column} @var{file}
-@end example
-@item vim
- this will invoke
-@example
-gvim --remote +:@var{line}:norm@var{char} @var{file}
-@end example
-
-@item nedit
-this will invoke
-@example
- nc -noask +@var{line} @var{file}'
-@end example
-@end table
-
-The environment variable @code{LYEDITOR} is used to override this. It
-contains the command line to start the editor, where @code{%(file)s},
-@code{%(column)s}, @code{%(line)s} is replaced with the file, column
-and line respectively. The setting
-
-@example
-emacsclient --no-wait +%(line)s:%(column)s %(file)s
-@end example
-
-@noindent
-for @code{LYEDITOR} is equivalent to the standard emacsclient
-invocation.
-
-
-@cindex file size, output
-
-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
-
-@example
-\pointAndClickOff
-@end example
-
-@noindent
-in a @file{.ly} file. Point and click may be explicitly enabled with
-
-@example
-\pointAndClickOn
-@end example
-
-Alternately, you may disable point and click with a command-line
-option:
-
-@example
-lilypond -dno-point-and-click file.ly
-@end example
-
-@warning{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.}
-@node Text editor support
-@section Text editor support
-
-@cindex editors
-@cindex vim
-@cindex emacs
-@cindex modes, editor
-@cindex syntax coloring
-@cindex coloring, syntax
-
-There is support for different text editors for LilyPond.
-
-@menu
-* Emacs mode::
-* Vim mode::
-* Other editors::
-@end menu
-
-@node Emacs mode
-@unnumberedsubsec Emacs mode
-
-Emacs has a @file{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 @file{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 @file{elisp} directory. Do @command{make
-install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
-should be placed to @var{load-path}@file{/site-start.d/} or appended
-to your @file{~/.emacs} or @file{~/.emacs.el}.
-
-As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
-your @var{load-path} by appending the following line (as modified) to your
-@file{~/.emacs}
-
-@c any reason we do not advise: (push "~/site-lisp" load-path)
-@example
-(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
-@end example
-
-
-@node Vim mode
-@unnumberedsubsec Vim mode
-
-For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} 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}
-directory.
-
-The LilyPond file type is detected if the file
-@file{~/.vim/filetype.vim} has the following content
-
-@example
-if exists("did_load_filetypes")
- finish
-endif
-augroup filetypedetect
- au! BufNewFile,BufRead *.ly,*.ily setf lilypond
-augroup END
-@end example
-
-Please include this path by appending the following line to your
-@file{~/.vimrc}
-
-@example
-set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
+\override VerticalAxisGroup #'staff-affinity = ##f
@end example
@noindent
-where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not
-installed in @file{/usr/local/}, then change this path accordingly.
-
-
-@node Other editors
-@unnumberedsubsec 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 @rgeneral{Alternate editors}.
-
+at its start. For details, see @qq{Spacing of non-staff lines} in
+@ruser{Flexible vertical spacing within systems}.
projects / lilypond.git / blobdiff