Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.14.0"
@node Running lilypond
* Invoking lilypond::
* Command line options for lilypond::
* Environment variables::
+* LilyPond in chroot jail::
@end menu
@node Invoking lilypond
@var{base}@file{-cello-1.pdf}.
+@unnumberedsubsubsec 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:
+
+@itemize
+
+@item
+@code{lilypond file.ly 1>stdout.log} to redirect normal output
+
+@item
+@code{lilypond file.ly 2>stderr.log} to redirect error messages
+
+@item
+@code{lilypond file.ly &>all.log} to redirect all output
+
+@end itemize
+
+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.
+
+
@node Command line options for lilypond
@unnumberedsubsec Command line options for @command{lilypond}
@item -f,--format=@var{format}
which formats should be written. Choices for @code{format} are
-@code{svg}, @code{ps}, @code{pdf}, and @code{png}.
+@code{ps}, @code{pdf}, and @code{png}.
Example: @code{lilypond -fpng @var{filename}.ly}
The @code{-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.
@item eps
-@cindex Postscript, encapulated
+@cindex Postscript, encapsulated
@cindex EPS (Encapsulated PostScript)
for encapsulated PostScript. This dumps every page (system) as a separate
@item preview
@cindex preview, command line
Generate 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.
+The @code{ps}, @code{eps}, and @code{svg} backends support this
+option.
+
+@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 @code{-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
@item -H,--header=@var{FIELD}
Dump a header field to file @file{BASENAME.@var{FIELD}}.
-@item --include, -I=@var{directory}
-Add @var{directory} to the search path for input files.
@cindex file searching
@cindex search path
+@item --include, -I=@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.
@item -i,--init=@var{file}
Set init file to @var{file} (default: @file{init.ly}).
-@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)
+@cindex loglevel
+@cindex output verbosity, setting
+
+@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 (default)
+All progress messages, warnings and errors.
+
+@item DEBUG
+All possible messages, including verbose debug output.
+@end table
+
+
+@cindex folder, directing output to
+@cindex output filename, setting
+
+@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 PostScript output
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 @code{--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
* 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
UTF-8 encoding. For details, see @ruser{Text encoding}.
+@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
+\override VerticalAxisGroup #'staff-affinity = ##f
+@end example
+
+@noindent
+at its start. For details, see @qq{Spacing of non-staff lines} in
+@ruser{Flexible vertical spacing within systems}.
projects / lilypond.git / blobdiff