-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Running LilyPond
@chapter Running LilyPond
@menu
-* Invoking lilypond::
-* Error messages::
-* Reporting bugs::
-* Editor support::
-* Invoking lilypond-latex::
+* Invoking lilypond::
+* Error messages::
+* Updating files with convert-ly::
+* Reporting bugs::
+* Editor support::
+* File structure::
+* Including LilyPond files::
@end menu
@node Invoking lilypond
@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. The function @code{ly:set-option} allows access to
-some internal variables. Use @code{-e '(ly:option-usage)'} for more
-information.
+sequentially.
@item -f,--format=@var{format}
-which formats should be written. Choices are @code{svg}, @code{ps},
+which formats should be written. Choices are @code{svg}, @code{ps},
@code{pdf}, @code{png}, @code{tex}, @code{dvi}.
@item -b,--backend=@var{format}
(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
extents of strings of text.
@item ps
- for PostScript
+ for PostScript.
@cindex PostScript output
+
+ 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
- for encapsulated PostScript. This dumps every page (system) as a separate
+ 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 lilypond-book.
+This mode is used by default by lilypond-book.
@item svg
for SVG (Scalable Vector Graphics)
@cindex output format, setting
+@item -d,--define-default=@var{var}=@var{val}
+This sets the internal program option @var{var} to the Scheme value
+@var{val}. If @var{val} is not supplied, then @var{#t} is used. To
+switch off an option, @code{no-} may be prefixed to @var{var}, eg.
+@example
+-dno-point-and-click
+@end example
+
+@noindent
+is the same as
+@example
+-dpoint-and-click='#f'
+@end example
+
+@cindex point and click
+
+Setting the @code{help} option will print a summary of the options
+available, and exit.
+
@item -h,--help
Show a summary of usage.
@item --dvi
Generate DVI files. In this case, the @TeX{} backend should be
-specified, i.e., @code{-f tex}.
+specified, i.e., @code{-b tex}.
@item --png
-Generate pictures of each page, in PNG format. This implies @code{--ps}.
+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 --pdf
Generate PDF. This implies @code{--ps}.
@item -s,--safe
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
+havoc, for example
+
When LilyPond formatting is available through a web server, the
@code{--safe} @b{MUST} be passed. This will prevent inline Scheme
code from wreaking havoc, for example
In @code{--safe} mode, it is not possible to import LilyPond variables
into Scheme.
-@code{--safe} does @emph{not} detect resource overuse. It is still
+@code{--safe} 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.
+Note that @code{--safe} will prevent many useful LilyPond snippets from
+being compiled. For a softer but secure alternative you can use the
+@code{--jail} option.
+
+
+@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
+Run 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
+server or whenever LilyPond executes externally provided
+sources.
+
+The @code{--jail} option works by changing the root of 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 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
+@code{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.
+
+@item Setting up a separate user
+A separate user and group (say, @samp{lily}/@samp{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
+@var{dir}.
+
+@item 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 apper in the
+real root filesystem. The entire content of the LilyPond installation
+(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.
+@end table
+
+
@item -v,--version
Show version information.
@section Environment variables
-For processing both the @TeX{} and the PostScript output, the
-appropriate environment variables must be set. The following scripts
-do this:
-
-@itemize @bullet
-@item @file{buildscripts/@/out/@/lilypond@/-profile}
-(for SH shells)
-@item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells)
-@end itemize
-
-They should normally be sourced as part of the login process. If these
-scripts are not run from the system wide login process, then you must
-run them yourself.
-
-@cindex installing LilyPond
-
-If you use sh, bash, or a similar shell, then add the following to
-your @file{.profile}:
-@example
-. @var{/the/path/to/}lilypond-profile
-@end example
-If you use csh, tcsh or a similar shell, then add the following to
-your @file{~/.login}:
-@example
-source @var{/the/path/to/}lilypond-login
-@end example
-
-Of course, in both cases, you should substitute the proper location of
-either script.
-
-These scripts set the following variables:
-@table @code
-@item TEXMF
-To make sure that @TeX{} and lilypond find data files (among
-others @file{.tex}, @file{.mf}, and @file{.tfm}),
-you have to set @code{TEXMF} to point to the lilypond data
-file tree. A typical setting would be
-@example
-@{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@}
-@end example
-
-@end table
-
-
-@cindex PostScript
-@cindex TEXMF
-@cindex printing postscript
+@cindex LANG
+@cindex LILYPONDPREFIX
-The binary itself recognizes the following environment variables:
+@code{Lilypond} recognizes the following environment variables:
@table @code
@item LILYPONDPREFIX
This specifies a directory where locale messages and
@item LANG
This selects the language for the warning messages.
+
+@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}.
+
@end table
-@cindex LANG
-@cindex LILYPONDPREFIX
@node Error messages
@section Error messages
above the indicated position.
+@node Updating files with convert-ly
+@section Updating with @command{convert-ly}
+
+@cindex Updating a LilyPond file
+@cindex @code{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 @command{convert-ly} can be used to deal with most of the
+syntax changes between LilyPond versions.
+
+It uses @code{\version} statements in the input files to detect the
+old version number. In most cases, to upgrade your input file it is
+sufficient to run@footnote{MacOS X users may execute this command
+under the menu entry @samp{Compile > Update syntax}.}
+
+@example
+convert-ly -e myfile.ly
+@end example
+
+If there are no changes to myfile.ly and file called myfile.ly.NEW
+is created, then myfile.ly is already updated.
+
+@command{convert-ly} always converts up to the last syntax change handled by
+it. This means that the @code{\version} number left in the file is
+usually lower than the version of @command{convert-ly} itself.
+
+To upgrade LilyPond fragments in texinfo files, use
+
+@example
+convert-ly --from=... --to=... --no-version *.itely
+@end example
+
+To upgrade many files at once, combine @code{convert-ly} with
+standard unix commands. This example will upgrade all @code{.ly}
+files in the current directory
+
+@example
+for f in *.ly; do convert-ly -e $f; done;
+@end example
+
+In general, the program is invoked as follows:
+
+@example
+convert-ly [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+
+The following options can be given:
+
+@table @code
+@item -e,--edit
+Do an inline edit of the input file. Overrides @code{--output}.
+
+@item -f,--from=@var{from-patchlevel}
+Set the version to convert from. If this is not set, @command{convert-ly}
+will guess this, on the basis of @code{\version} strings in the file.
+
+@item -n,--no-version
+Normally, @command{convert-ly} adds a @code{\version} indicator
+to the output. Specifying this option suppresses this.
+
+@item -s, --show-rules
+Show all known conversions and exit.
+
+@item --to=@var{to-patchlevel}
+Set the goal version of the conversion. It defaults to the latest
+available version.
+
+@item -h, --help
+Print usage help.
+@end table
+
+
+@refbugs
+
+Not all language changes are handled. Only one output option can be
+specified.
+
+
+@c We might want to make this a completely new section, along with more
+@c info about how to upgrade old input files. -gp
+
+@ignore
+Copy and paste from CVS, last updated
+Aug 18, 2005
+
+http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
+@end ignore
+@verbatim
+
+There are a few things that the convert-ly cannot handle. Here's a list of limitations
+that the community has complained about.
+
+This bug report structure has been chosen because convert-ly has a structure that doesn't
+allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
+here for reference.
+
+1.6->2.0:
+ Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
+ To be able to run convert-ly
+ on it, I first replaced all occurencies of '{<' to some dummy like '{#'
+ and similarly I replaced '>}' with '&}'. After the conversion, I could
+ then change back from '{ #' to '{ <' and from '& }' to '> }'.
+ Doesn't convert all text markup correctly. In the old markup syntax,
+ it was possible to group a number of markup commands together within parentheses, e.g.
+ -#'((bold italic) "string")
+ This will incorrectly be converted into
+ -\markup{{\bold italic} "string"}
+ instead of the correct
+ -\markup{\bold \italic "string"}
+2.0->2.2:
+ Doesn't handle \partcombine
+ Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
+2.0->2.4:
+ \magnify isn't changed to \fontsize.
+ - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
+ remove-tag isn't changed.
+ - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
+ firstpagenumber isn't changed.
+ - firstpagenumber no => printfirstpagenumber = ##f
+ Line breaks in header strings aren't converted.
+ - \\\\ as line break in \header strings => \markup \center-align <
+ "First Line" "Second Line" >
+ Crescendo and decrescendo terminators aren't converted.
+ - \rced => \!
+ - \rc => \!
+2.2->2.4:
+ \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
+2.4.2->2.5.9
+ \markup{ \center-align <{ ... }> } should be converted to:
+ \markup{ \center-align {\line { ... }} }
+ but now, \line is missing.
+2.4->2.6
+ Special LaTeX characters such as $~$ in text are not converted to UTF8.
+
+@end verbatim
+
+
@node Reporting bugs
@section Reporting bugs
problem. Don't forget to tell which version of LilyPond you use! Send
the report to @email{bug-lilypond@@gnu.org}.
+@ignore
+@c the bug database is not up to date enough.
+
When you've found a bug, have a look at our
-@uref{http://@/lilypond@/.org/@/doc/@/v2.3/@/bugs/,bug database} to see if
+@uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
it has already been reported. You could also try to do a few searches
on the mailing list for the bug. Sometimes the bug will have already
been reported and a fix or workaround is already known.
+@end ignore
Here is an example of a good bug report:
It seems that placement of accidentals is broken. In the
following example, the accidental touches the note head.
-Using Mac OSX 10.3.5, fink package lilypond-unstable
+Using Mac OSX 10.3.7, fink package lilypond-devel
-\version "2.3.22"
+\version "2.5.18"
\relative c''@{
a4 b cis d
@}
@end example
@lilypond[quote]
-\version "2.3.22"
+\version "2.5.18"
\relative c''{
\override Accidental #'extra-offset = #'(1.0 . 0)
a4 b cis d
manuals using Info. If @file{lilypond-mode} is not installed on your
platform, then read the
@ifhtml
-@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
+@uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
@end ifhtml
@ifnothtml
installation instructions.
For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
with syntax coloring tools. For more information, refer to the
@ifhtml
-@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
+@uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
@end ifhtml
@ifnothtml
installation instructions.
@item JEdit
-The @uref{http://@/www@/.jedit@/.org/,jEdit} editor has a LilyPond plugin.
+The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
This plugin includes a DVI viewer, integrated help and viewing via
GhostScript. It can be installed by doing @key{Plugins > Plugin
Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
of a symbol in the graphical output. See @ref{Point and click}.
+@node File structure
+@section File structure
+The major part of this manual is concerned with entering various
+forms of music in LilyPond. However, many music expressions are not
+valid input on their own, for example, a @code{.ly} file containing
+only a note
+@example
+c'4
+@end example
-@node Invoking lilypond-latex
-@section Invoking lilypond-latex
+@noindent
+will result in a parsing error. Instead, music should be inside other
+expressions, which may be put in a file by themselves. Such
+expressions are called toplevel expressions. This section enumerates
+them all.
-Before LilyPond 2.4, the @code{lilypond} program only generated music
-notation. Titles and page layout was done in a separate wrapper
-program. For compatibility with older files, this wrapper program has
-been retained as @code{lilypond-latex}. It uses the LilyPond program
-and La@TeX{} to create a nicely titled piece of sheet music. Use of
-this program is only necessary if the input file contains special
-La@TeX{} options or formatting codes in markup texts.
+A @code{.ly} file contains any number of toplevel expressions, where a
+toplevel expression is one of the following
-The @code{lilypond-latex} wrapper is invoked from the command-line as
-follows
+@itemize @bullet
+@item
+An output definition, such as @code{\paper}, @code{\midi}, and
+@code{\layout}. Such a definition at the toplevel changes the default
+settings for the block entered.
+
+@item
+A @code{\header} block. This sets the global header block. This
+is the block containing the definitions for book-wide settings, like
+composer, title, etc.
+
+@item
+An @code{\addquote} statement. See @ref{Quoting other voices}
+for more information.
+
+@item
+A @code{\score} block. This score will be collected with other
+toplevel scores, and combined as a single @code{\book}.
+
+This behavior can be changed by setting the variable
+@code{toplevel-score-handler} at toplevel. The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
+
+The @code{\score} must begin with music, and may contain only
+one music block.
+
+@item
+A @code{\book} block logically combines multiple movements
+(i.e., multiple @code{\score} blocks) in one document. A number of
+@code{\scores} creates a single output file, where all movement are
+concatenated.
+
+This behavior can be changed by setting the variable
+@code{toplevel-book-handler} at toplevel. The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
+
+@item
+A compound music expression, such as
@example
-@code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
+@{ c'4 d' e'2 @}
@end example
-To have @code{lilypond-latex} read from stdin, use a dash (@code{-}) for
-@var{file}. The program supports the following options.
+This will add the piece in a @code{\score} and format it in a
+single book together with all other toplevel @code{\score}s and music
+expressions.
+
+This behavior can be changed by setting the variable
+@code{toplevel-music-handler} at toplevel. The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
-@cindex stdin, reading
+@item
+A markup text, a verse for example
+@example
+\markup @{
+ 2. The first line verse two.
+@}
+@end example
-@table @code
-@item -k,--keep
-Keep the temporary directory with all output files. The temporary
-directory is created in the current directory as @code{@code{lilypond}.dir}.
+Markup texts are rendered above, between or below the scores or music
+expressions, wherever they appear.
-@item -h,--help
-Print usage help.
+@item
+An indentifier, such as
+@example
+foo = @{ c4 d e d @}
+@end example
-@item -I,--include=@var{dir}
-Add @var{dir} to LilyPond's include path.
+This can be used later on in the file by entering @code{\foo}. The
+name of an identifier should have alphabetic characters only; no
+numbers, underscores or dashes.
-@item -o,--output=@var{file}
-Generate output to @var{file}. The extension of @var{file} is ignored.
+@end itemize
-@item --png
-Also generate pictures of each page, in PNG format.
+The following example shows three things that may be entered at
+toplevel
-@item --preview
-Also generate a picture of the first system of the score.
-
-@cindex preview
-@cindex picture
-@cindex bitmap
-@cindex pixmap
-@cindex thumbnail
-@cindex screen shot
-
-@item -s,--set=@var{key}=@var{val}
-Add @var{key}= @var{val} to the settings, overriding those specified
-in the files. Possible keys: @code{language}, @code{latexheaders},
-@code{latexpackages}, @code{latexoptions}, @code{papersize},
-@code{linewidth}, @code{orientation},
-@code{textheight}.
+@example
+\layout @{
+ % movements are non-justified by default
+ raggedright = ##t
+@}
-@item -v,--version
-Show version information.
+\header @{
+ title = "Do-re-mi"
+@}
+
+@{ c'4 d' e2 @}
+@end example
-@item -V,--verbose
-Be verbose. This prints out commands as they are executed, and more
-information about the formatting process is printed.
-@item --debug
-Print even more information. This is useful when generating bug reports.
+At any point in a file, any of the following lexical instructions can
+be entered:
-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
+@itemize @bullet
+@item @code{\version}
+@item @code{\include}
+@item @code{\renameinput}
+@end itemize
-@subsection Additional parameters
+@node Including LilyPond files
+@section Including LilyPond files
-The @code{lilypond} program responds to several parameters specified
-in a @code{\layout} section of the input file. They can be overridden
-by supplying a @code{--set} command line option.
+@cindex @code{\include}
+@cindex including files
+
+A large project may be split up into separate files. To refer to another
+file, use
+
+@example
+\include "otherfile.ly"
+@end example
+
+The line @code{\include "file.ly"} is equivalent to pasting the contents
+of file.ly into the current file at the place where you have the
+\include. For example, for a large project you might write separate files
+for each instrument part and create a ``full score'' file which brings
+together the individual instrument files.
+
+The initialization of LilyPond is done in a number of files that are
+included by default when you start the program, normally transparent to the
+user. Run lilypond --verbose to see a list of paths and files that Lily
+finds.
+
+Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
+VERSION is in the form ``2.6.1'') are on the path and available to
+@code{\include}. Files in the
+current working directory are available to \include, but a file of the same
+name in LilyPond's installation takes precedence. Files are
+available to \include from directories in the search path specified as an
+option when invoking @code{lilypond --include=DIR} which adds DIR to the search
+path.
+
+The @code{\include} statement can use full path information, but with the Unix
+convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
+if @file{stuff.ly} is located one directory higher than the current working
+directory, use
+
+@example
+\include "../stuff.ly"
+@end example
-@table @code
-@item language
-Specify La@TeX{} language: the @code{babel} package will be
-included. Default: unset.
-
-Read from the @code{\header} block.
-
-@item latexheaders
-Specify additional La@TeX{} header files.
-Normally read from the @code{\header} block. Default value: empty.
-
-@item latexpackages
-Specify additional La@TeX{} package files. This works cumulative,
-so you can add multiple packages using multiple @code{-s=latexpackages} options.
-Normally read from the @code{\header} block. Default value:
-@code{geometry}.
-
-@item latexoptions
-Specify additional options for the La@TeX{}
-@code{\documentclass}. You can put any valid value here. This was
-designed to allow @code{lilypond} to produce output for double-sided
-paper, with balanced margins and page numbers on alternating sides. To
-achieve this specify @code{twoside}.
-
-@item orientation
-Set orientation. Choices are @code{portrait} or @code{landscape}. Is
-read from the @code{\layout} block, if set.
-
-@item textheight
-The vertical extension of the music on the page. It is normally
-calculated automatically, based on the paper size.
-
-@item linewidth
-The music line width. It is normally read from the @code{\layout}
-block.
-
-@item papersize
-The paper size (as a name, e.g., @code{a4}). It is normally read from
-the @code{\layout} block.
-
-@item fontenc
-The font encoding, should be set identical to the @code{font-encoding}
-property in the score.
-@end table
projects / lilypond.git / blobdiff