@c \version "2.12.0"
-@node Running LilyPond
-@chapter Running LilyPond
+@node Running lilypond
+@chapter Running @command{lilypond}
This chapter details the technicalities of running LilyPond.
* Normal usage::
* Command-line usage::
* Error messages::
-* Updating files with convert-ly::
-* Reporting bugs::
@end menu
@node Normal usage
@section Normal usage
-Most users run LilyPond through a GUI; see @rlearning{First steps} if
-you have not read this already.
+Most users run LilyPond through a GUI; see @rlearning{First steps}
+if you have not read this already.
@node Command-line usage
By @q{command-line}, we mean the command line in the operating system.
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}. They should also consult @ref{Setup
-for MacOS X}.
+@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}.
Describing how to use this part of an operating system is outside the
scope of this manual; please consult other documentation on this topic
@end menu
@node Invoking lilypond
-@subsection Invoking @command{lilypond}
+@unnumberedsubsec Invoking @command{lilypond}
-@cindex Invoking @command{lilypond}
-@cindex command line options for @command{lilypond}
-@cindex options, command line
-@cindex switches
-
-
-The @command{lilypond} executable may be called as follows from the command line.
+The @command{lilypond} executable may be called as follows from
+the command line.
@example
lilypond [@var{option}]@dots{} @var{file}@dots{}
GUILE is not reset after processing a @code{.ly} file, so be careful
not to change any system defaults from within Scheme.}
-If @file{filename.ly} contains more than one @code{\score}
+If @file{filename.ly} contains more than one @code{\book}
block, then the rest of the scores will be output in numbered files,
starting with @file{filename-1.pdf}. In addition, the value of
@code{output-suffix} will be inserted between the basename and the
@node Command line options for lilypond
-@subsection Command line options for @command{lilypond}
+@unnumberedsubsec Command line options for @command{lilypond}
+
+@cindex Invoking @command{lilypond}
+@cindex command line options for @command{lilypond}
+@cindex options, command line
+@cindex switches
The following options are supported:
Here are a few interesting options.
+@cindex help, command line
+
@table @samp
@item help
Running @code{lilypond -dhelp} will print all of the @code{-d} options
available.
+@cindex paper-size, command line
+
@item paper-size
This option sets the default paper-size,
@example
Note that the string must be enclosed in escaped quotes ( @code{\"} ).
@c Match " in previous line to help context-sensitive editors
+@cindex safe, command line
+
@item safe
Do not trust the @code{.ly} input.
lead to huge files.
@item eps
+
+@cindex Postscript, encapulated
+@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.
This mode is used by default by @command{lilypond-book}.
@item svg
+
@cindex SVG (Scalable Vector Graphics)
+
for SVG (Scalable Vector Graphics).
- This creates a single SVG file containing the entire music
- output, with embedded fonts. You need an SVG viewer that
- supports embedded fonts, or an SVG viewer that can replace the
- embedded fonts with OTF fonts. Under UNIX, you may use
- @uref{http://www.inkscape.org,Inkscape} (version 0.42 or later),
- after copying the OTF fonts from the LilyPond directory
- (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
- @file{~/.fonts/}.
+ 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
+
for a dump of the raw, internal Scheme-based drawing commands.
@item null
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
@item print-pages
Set the default output file to @var{FILE}. The appropriate
suffix will be added (e.g. @code{.pdf} for pdf)
+@cindex PostScript output
+
@item --ps
Generate PostScript.
+@cindex Portable Network Graphics (PNG) output
+
@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
-dresolution=110
@end example
+@cindex Portable Document Format (PDF) output
+
@item --pdf
Generate PDF. This implies @code{--ps}.
@end table
@node Environment variables
-@subsection Environment variables
+@unnumberedsubsec Environment variables
@cindex LANG
input file.
@item Error
+@cindex error
Something is definitely wrong. The current processing step (parsing,
interpreting, or formatting) will be finished, but the next step will
be skipped.
@item Fatal error
-@cindex error
@cindex fatal error
Something is definitely wrong, and LilyPond cannot continue. This
happens rarely. The most usual cause is misinstalled fonts.
other output.
@item Aborted (core dumped)
+@cindex 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.
indicated line of your input file, try checking one or two lines
above the indicated position.
-
-@node Updating files with convert-ly
-@section Updating files with @command{convert-ly}
-
-@cindex Updating a LilyPond file
-@cindex 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.
-
-@menu
-* Invoking convert-ly::
-* Command line options for convert-ly::
-* Problems with convert-ly::
-@end menu
-
-@node Invoking convert-ly
-@subsection Invoking @command{convert-ly}
-
-@command{convert-ly} uses @code{\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
-
-@example
-convert-ly -e myfile.ly
-@end example
-
-@noindent
-in the directory containing the file. This will upgrade
-@code{myfile.ly} in-place and preserve the original file in
-@code{myfile.ly~}.
-
-To convert all the input files in a directory together use
-
-@example
-convert-ly -e *.ly
-@end example
-
-Alternatively, if you want to specify a different name for the
-upgraded file, preserving the original file and name unchanged,
-use
-
-@example
-convert-ly myfile.ly > mynewfile.ly
-@end example
-
-@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.
-
-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.
-
-@noindent
-MacOS@tie{}X users may execute these commands under the menu entry
-@code{Compile > Update syntax}.
-
-Windows users should enter these commands in a Command Prompt window,
-which is usually found under
-@code{Start > Accessories > Command Prompt}.
-
-@node Command line options for convert-ly
-@subsection Command line options for @command{convert-ly}
-
-In general, the program is invoked as follows:
-
-@example
-convert-ly [@var{option}]@dots{} @var{filename}@dots{}
-@end example
-
-
-The following options can be given:
-
-@table @code
-@item -e,--edit
-Apply the conversions direct to the input file, modifying it
-in-place.
-
-@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.
-E.g. @code{--from=2.10.25}
-
-@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. E.g. @code{--to=2.12.2}
-
-@item -h, --help
-Print usage help.
-@end table
-
-To upgrade LilyPond fragments in texinfo files, use
-
-@example
-convert-ly --from=... --to=... --no-version *.itely
-@end example
-
-To see the changes in the LilyPond syntax between two versions, use
-
-@example
-convert-ly --from=... --to=... -s
-@end example
-
-
-@node Problems with convert-ly
-@subsection Problems with @code{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:
-
-@example
-convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
-@end example
-
-If the simple @command{convert-ly -e *.ly} command fails because the
-expanded command line becomes too long, the @command{convert-ly}
-command may be placed in a loop instead. This example for UNIX
-will upgrade all @code{.ly} files in the current directory
-
-@example
-for f in *.ly; do convert-ly -e $f; done;
-@end example
-
-In the Windows Command Prompt window the corresponding command is
-
-@example
-for %x in (*.ly) do convert-ly -e """%x"""
-@end example
-
-Not all language changes are handled. Only one output option can be
-specified. Automatically updating scheme and LilyPond scheme
-interfaces is quite unlikely; be prepared to tweak scheme code
-manually.
-
-@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 occurrences 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 #'. . .
- first-page-number isn't changed.
- - first-page-number no => print-first-page-number = ##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.
-2.8
- \score{} must now begin with a music expression. Anything else
- (particularly \header{}) must come after the music.
-@end verbatim
-
-
-@node Reporting bugs
-@section Reporting bugs
-
-@cindex bugs
-@cindex reporting bugs
-
-If you have input that results in a crash or an erroneous output, then
-that is a bug. There is a list of current bugs on our Google bug tracker,
-
-@uref{http://code.google.com/p/lilypond/issues/list}
-
-If you have discovered a bug which is not listed, please report the
-bug by following the directions on
-
-@uref{http://lilypond.org/web/devel/participating/bugs}
-
-Please construct and submit minimal examples of bugs in reports. We do not
-have the resources to investigate reports which are not as small as possible.
-
+More information about errors is given in @ref{Common errors}.
projects / lilypond.git / blobdiff