@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-program.tely
@ignore
Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.12.0"
+
@node Running LilyPond
@chapter Running LilyPond
This chapter details the technicalities of running LilyPond.
-Some of these commands are run from the command-line. 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}; OSX users might be more familiar with the
-terms @q{terminal} or @q{console}. OSX users should also
-consult @ref{Notes for the MacOS X app}.
+@menu
+* 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.
+
-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.
+@node Command-line usage
+@section Command-line usage
+
+This section contains extra information about using LilyPond on the
+command-line. This may be desirable to pass extra options to the
+program. In addition, there are certain extra @q{helper} programs (such
+as @code{midi2ly}) which are only available on the command-line.
+
+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}.
+
+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::
-* Notes for the MacOS X app::
-* Updating files with convert-ly::
-* Reporting bugs::
-* Error messages::
-* Editor support::
-* Point and click::
+* Invoking lilypond::
+* Command line options for lilypond::
+* Environment variables::
@end menu
@node Invoking lilypond
-@section Invoking lilypond
-@cindex Invoking LilyPond
-@cindex command line options
+@subsection Invoking @command{lilypond}
+
+@cindex Invoking @command{lilypond}
+@cindex command line options for @command{lilypond}
@cindex options, command line
@cindex switches
-The @code{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{}
extension is tried first. To read input from stdin, use a
dash (@code{-}) for @var{file}.
-When @file{filename.ly} is processed it will produce
-@file{filename.tex} as output (or @file{filename.ps} for PostScript
-output). If @file{filename.ly} contains more than one @code{\score}
-block, then the rest of the scores will be output in numbered files,
-starting with @file{filename-1.tex}. Several files can be specified;
+When @file{filename.ly} is processed it will produce @file{filename.ps}
+and @file{filename.pdf} as output. Several files can be specified;
they will each be processed independently. @footnote{The status of
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}
+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
+number. An input file containing
+
+@example
+#(define output-suffix "violin")
+\book @{ @dots{} @}
+#(define output-suffix "cello")
+\book @{ @dots{} @}
+@end example
+
+@noindent
+will output @var{base}@file{-violin.pdf} and
+@var{base}@file{-cello-1.pdf}.
-@subsection Command line options
+
+@node Command line options for lilypond
+@subsection Command line options for @command{lilypond}
The following options are supported:
@item -f,--format=@var{format}
which formats should be written. Choices for @code{format} are
-@code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+@code{svg}, @code{ps}, @code{pdf}, and @code{png}.
-Example: @code{lilypond -fpng filename.ly}
+Example: @code{lilypond -fpng @var{filename}.ly}
@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
+@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}, e.g.
@cindex point and click, command line
available.
@item paper-size
-This option sets the default paper-size,
+This option sets the default paper-size,
@example
-dpaper-size=\"letter\"
@end example
@noindent
Note that the string must be enclosed in escaped quotes ( @code{\"} ).
-
+@c Match " in previous line to help context-sensitive editors
@item safe
Do not trust the @code{.ly} input.
In safe mode, it is not possible to import LilyPond variables
into Scheme.
-safe does @emph{not} detect resource overuse. It is still possible to
+@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
compiled. The @code{--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
@table @code
-@item tex
-for @TeX{} output, to be processed with La@TeX{}. If present, the file
-@file{file.textmetrics} is read to determine text extents.
-@item texstr
-dump text strings to @file{.texstr} file, which can be run through
-(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
-extents of strings of text. @strong{Warning:} this functionality is
-currently missing due to heavy restructuring of the source code.
@item ps
- for PostScript.
@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
@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 @command{lilypond-book}.
@item svg
+@cindex SVG (Scalable Vector Graphics)
for SVG (Scalable Vector Graphics). This dumps every page as a separate
@file{SVG} file, with embedded fonts.
-@cindex SVG (Scalable Vector Graphics)
You need a SVG viewer which supports embedded fonts, or a SVG
viewer which is able to 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 in directory
- @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.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/}.
@item scm
- for a dump of the raw, internal Scheme-based drawing commands.
@cindex Scheme dump
-@end table
+ for a dump of the raw, internal Scheme-based drawing commands.
-Example: @code{lilypond -dbackend=svg filename.ly}
+@item null
+ do not output a printed score; has the same effect as @code{-dno-print-pages}.
+@end table
-@cindex output format, setting
+Example: @code{lilypond -dbackend=svg @var{filename}.ly}
@item preview
Generate an output file containing the titles and the first system
@item -h,--help
Show a summary of usage.
-@item -H,--header=FIELD
-Dump a header field to file BASENAME.FIELD
+@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.
@item -o,--output=@var{FILE}
Set the default output file to @var{FILE}. The appropriate
-suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
-for tex, etc).
+suffix will be added (e.g. @code{.pdf} for pdf)
@item --ps
Generate PostScript.
-@item --dvi
-Generate DVI files. In this case, the @TeX{} backend should be
-specified, i.e., @code{-b tex}.
-
@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
@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
-Run LilyPond in a chroot jail.
+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
server or whenever LilyPond executes externally provided
sources.
-The @code{--jail} option works by changing the root of LilyPond to
+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 LilyPond must be run as root, which is usually
+@code{--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:
+@emph{inside the jail}. A typical setup comprises the following items:
@table @asis
@item Setting up a separate filesystem
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
+A separate user and group (say, @code{lily}/@code{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}.
@strong{NO WARRANTY}!)
@end table
-
+@node Environment variables
@subsection Environment variables
@cindex LANG
@cindex LILYPOND_DATADIR
-@code{Lilypond} recognizes the following environment variables:
+@command{lilypond} recognizes the following environment variables:
@table @code
@item LILYPOND_DATADIR
This specifies a directory where locale messages and
@item LILYPOND_GC_YIELD
With this variable the memory footprint and performance can be
-adjusted. It is a percentage tunes memory management behavior. With
+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}.
+uses more CPU time. The default value is @code{70}.
@end table
-@node Notes for the MacOS X app
-@section Notes for the MacOS X app
+@node Error messages
+@section Error messages
-The scripts (such as lilypond-book, convert-ly, abc2ly, and even
-lilypond itself) are also
-included inside MacOS X .app. They can be run from the command line by
-invoking them directly, e.g.
+@cindex error messages
+Different error messages can appear while compiling a file:
-@example
-@var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
-@end example
+@table @emph
-@noindent
-The same is true of the other scripts in that directory, including
-lilypond-book, convert-ly, abc2ly, etc.
+@item Warning
+@cindex warning
+Something looks suspect. If you are requesting something out of the
+ordinary then you will understand the message, and can ignore it.
+However, warnings usually indicate that something is wrong with the
+input file.
-Alternatively, you may create scripts which add the path
-automatically. Create a directory to store these scripts,
+@item Error
+Something is definitely wrong. The current processing step (parsing,
+interpreting, or formatting) will be finished, but the next step will
+be skipped.
-@example
-mkdir -p ~/bin
-cd ~/bin
-@end example
+@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.
-Create a file called @code{lilypond} which contains
+@item Scheme error
+@cindex trace, Scheme
+@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
+function call is printed.
-@example
-exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
-@end example
+@item Programming error
+@cindex Programming error
+There was some internal inconsistency. These error messages are
+intended to help the programmers and debuggers. Usually, they can be
+ignored. Sometimes, they come in such big quantities that they obscure
+other output.
-Create similar files @code{lilypond-book}, @code{convert-ly}, and
-any other helper programs you use (@code{abc2ly}, @code{midi2ly},
-etc). Simply replace the @code{bin/lilypond} with
-@code{bin/convert-ly} (or other program name) in the above file.
+@item 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.
+@end table
-Make the file executable,
+@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
@example
-chmod u+x lilypond
+@var{filename}:@var{lineno}:@var{columnno}: @var{message}
+@var{offending input line}
@end example
-Now, add this directory to your path. Modify (or create)
-a file called @code{.profile} in your home directory such that it contains
+A line-break is inserted in the offending line to indicate the column
+where the error was found. For example,
@example
-export PATH=$PATH:~/bin
+test.ly:2:19: error: not a duration: 5
+ @{ c'4 e'
+ 5 g' @}
@end example
-@noindent
-This file should end with a blank line.
-
-Note that @var{path/to} will generally be @code{/Applications/}.
+These locations are LilyPond's best guess about where the warning or
+error occurred, but (by their very nature) warnings and errors occur
+when something unexpected happens. If you can't see an error in the
+indicated line of your input file, try checking one or two lines
+above the indicated position.
@node Updating files with convert-ly
-@section Updating with @command{convert-ly}
+@section Updating files with @command{convert-ly}
@cindex Updating a LilyPond file
-@funindex convert-ly
+@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
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}.}
+sufficient to run
@example
convert-ly -e myfile.ly
@end example
+@noindent
+MacOS@tie{}X users may execute this command under the menu entry
+@code{Compile > Update syntax}.
+
If there are no changes to myfile.ly and file called myfile.ly.NEW
is created, then myfile.ly is already updated.
+@menu
+* Command line options for convert-ly::
+* Problems with convert-ly::
+@end menu
+
+@node Command line options for convert-ly
+@subsection Command line options for @command{convert-ly}
+
@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.
@end example
To upgrade many files at once, combine @code{convert-ly} with
-standard unix commands. This example will upgrade all @code{.ly}
+standard UNIX commands. This example will upgrade all @code{.ly}
files in the current directory
@example
@end table
-@refbugs
+@node Problems with convert-ly
+@subsection Problems with @code{convert-ly}
Not all language changes are handled. Only one output option can be
-specified. Automatically updating scheme and lilypond scheme
+specified. Automatically updating scheme and LilyPond scheme
interfaces is quite unlikely; be prepared to tweak scheme code
manually.
-
-@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
-
-NEW: not exactly copied; this list has been modified. Since we're
-changing the bug system, it doesn't make sense to copy from
-the bug CVS any more. I'll figure out something else. -gp
-@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.
-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.
+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:
+>}. 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
+ 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,
+ 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")
@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,
+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}
@uref{http://lilypond.org/web/devel/participating/bugs}
-Please construct submit @ref{Minimal examples} of bug reports. We do not
+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.
-@node Error messages
-@section Error messages
-
-@cindex error messages
-Different error messages can appear while compiling a file:
-
-@table @emph
-@cindex warning
-
-@item Warning
-Something looks suspect. If you are requesting something out of the
-ordinary then you will understand the message, and can ignore it.
-However, warnings usually indicate that something is wrong with the
-input file.
-
-@item Error
-Something is definitely wrong. The current processing step (parsing,
-interpreting, or formatting) will be finished, but the next step will
-be skipped.
-
-@cindex error
-@cindex fatal error
-@item Fatal error
-Something is definitely wrong, and LilyPond cannot continue. This
-happens rarely. The most usual cause is misinstalled fonts.
-
-@cindex trace, Scheme
-@cindex call trace
-@cindex Scheme error
-@item 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
-function call is printed.
-
-@cindex Programming error
-@item Programming error
-There was some internal inconsistency. These error messages are
-intended to help the programmers and debuggers. Usually, they can be
-ignored. Sometimes, they come in such big quantities that they obscure
-other output. In this case, file a bug-report.
-
-@item 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.
-
-
-@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
-
-@example
-@var{filename}:@var{lineno}:@var{columnno}: @var{message}
-@var{offending input line}
-@end example
-
-A line-break is inserted in the offending line to indicate the column
-where the error was found. For example,
-
-@example
-test.ly:2:19: error: not a duration: 5:
- @{ c'4 e'5
- g' @}
-@end example
-
-These locations are LilyPond's best guess about where the warning or
-error occurred, but (by their very nature) warnings and errors occur
-when something unexpected happens. If you can't see an error in the
-indicated line of your input file, try checking one or two lines
-above the indicated position.
-
-
-@node Editor support
-@section Editor support
-
-@cindex editors
-@cindex vim
-@cindex emacs
-@cindex modes, editor
-@cindex syntax coloring
-@cindex coloring, syntax
-
-There is support from different editors for LilyPond.
-
-@table @asis
-@item Emacs
-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, then read the
-@ifhtml
-@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
-@end ifhtml
-@ifnothtml
-installation instructions.
-@end ifnothtml
-
-@item VIM
-
-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{source/Documentation/topdocs/INSTALL.html,installation instructions}.
-@end ifhtml
-@ifnothtml
-installation instructions.
-@end ifnothtml
-
-
-@item LilyPondTool
-
-Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} text
-editor, LilyPondTool is the most feature-rich text-based tool for editing
-LilyPond scores. Its features include a Document Wizard with lyrics
-support to set up documents easier, and embedded PDF viewer with advanced
-point-and-click support. For screenshots, demos and installation
-instructions, visit @uref{http://lilypondtool@/.organum@/.hu}
-
-@end table
-
-All these editors can be made to jump into the input file to the source
-of a symbol in the graphical output. See @ref{Point and click}.
-
-
-@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.}
-
-@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
-#(ly:set-option 'point-and-click #f)
-@end example
-
-@noindent
-in a @file{.ly} file. Alternately, you may pass this as an command-line
-option
-
-@example
-lilypond -dno-point-and-click file.ly
-@end example
projects / lilypond.git / blobdiff