@menu
* Invoking lilypond::
* Error messages::
+* Updating files with convert-ly::
* Reporting bugs::
* Editor support::
-* Invoking lilypond-latex::
@end menu
@node Invoking lilypond
information.
@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}
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
+ 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 defines an internal variable @var{var} as the Scheme value
+@var{val}.
+
+Supported values include:
+@table @code
+@item resolution
+set PNG resolution
+@item preview-include-book-title
+include book-titles in preview
+@end table
+
+These settings are returned when calling
+@code{(ly:get-option 'command-line-settings)} from Scheme.
+
@item -h,--help
Show a summary of usage.
@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 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.
above the indicated position.
+@node Updating files with convert-ly
+@section Updating with @command{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
+
+@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.
+
+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 -o,--output=@var{file}
+Set the output file to write.
+
+@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
+
+@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.
+
+@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
+Feb 14, 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. Only very simple cases are fixed.
+2.0->2.2:
+ Doesn't handle \partcombine
+ Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
+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.
+@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:
Using Mac OSX 10.3.5, fink package lilypond-unstable
-\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 Invoking lilypond-latex
-@section Invoking lilypond-latex
-
-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.
-
-The @code{lilypond-latex} wrapper is invoked from the command-line as
-follows
-@example
-@code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
-@end example
-
-To have @code{lilypond-latex} read from stdin, use a dash (@code{-}) for
-@var{file}. The program supports the following options.
-
-@cindex stdin, reading
-
-@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}.
-
-@item -h,--help
-Print usage help.
-
-@item -I,--include=@var{dir}
-Add @var{dir} to LilyPond's include path.
-
-@item -o,--output=@var{file}
-Generate output to @var{file}. The extension of @var{file} is ignored.
-
-@item --png
-Also generate pictures of each page, in PNG format.
-
-@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}.
-
-@item -v,--version
-Show version information.
-
-@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.
-
-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
-
-
-@subsection Additional parameters
-
-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.
-
-@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