+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond-program.tely
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- 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.
-
-@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.
-
-
-@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::
-* Command line options for lilypond::
-* Environment variables::
-@end menu
-
-@node Invoking lilypond
-@subsection 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.
-
-@example
-lilypond [@var{option}]@dots{} @var{file}@dots{}
-@end example
-
-
-When invoked with a filename that has no extension, the @file{.ly}
-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.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")
-\score @{ @dots{} @}
-#(define output-suffix "cello")
-\score @{ @dots{} @}
-@end example
-
-@noindent
-will output @var{base}@file{-violin.pdf} and
-@var{base}@file{-cello-1.pdf}.
-
-
-@node Command line options for lilypond
-@subsection Command line options for @command{lilypond}
-
-The following options are supported:
-
-@table @code
-
-@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 expression will be evaluated in the @code{guile-user} module, so
-if you want to use definitions in @var{expr}, use
-
-@example
-lilypond -e '(define-public a 42)'
-@end example
-
-@noindent
-on the command-line, and include
-
-@example
-#(use-modules (guile-user))
-@end example
-
-@noindent
-at the top of the @code{.ly} file.
-
-@item -f,--format=@var{format}
-which formats should be written. Choices for @code{format} are
-@code{svg}, @code{ps}, @code{pdf}, and @code{png}.
-
-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
-switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
-
-@cindex point and click, command line
-
-@example
--dno-point-and-click
-@end example
-
-@noindent
-is the same as
-@example
--dpoint-and-click='#f'
-@end example
-
-Here are a few interesting options.
-
-@table @samp
-@item help
-Running @code{lilypond -dhelp} will print all of the @code{-d} options
-available.
-
-@item 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.
-
-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
-
-@quotation
-@verbatim
-#(system "rm -rf /")
-{
- c4^#(ly:export (ly:gulp-file "/etc/passwd"))
-}
-@end verbatim
-@end quotation
-
-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}.
-
-In addition, safe mode disallows @code{\include} directives and
-disables the use of backslashes in @TeX{} strings.
-
-In safe mode, it is not possible to import LilyPond variables
-into Scheme.
-
-@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
-CPU and memory usage.
-
-The safe mode will prevent many useful LilyPond snippets from being
-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 ps
-@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
- lead to huge files.
-
-@item eps
- 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 dumps every page as a separate
-@file{SVG} file, with embedded fonts.
- 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 from the LilyPond directory
- (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}.
-@item scm
-@cindex Scheme dump
- for a dump of the raw, internal Scheme-based drawing commands.
-
-@item null
- do not output a printed score; has the same effect as @code{-dno-print-pages}.
-@end table
-
-Example: @code{lilypond -dbackend=svg @var{filename}.ly}
-
-@item preview
-Generate an output file containing the titles and the first system
-
-@item print-pages
-Generate the full pages, the default. @code{-dno-print-pages} is
-useful in combination with @code{-dpreview}.
-
-@end table
-
-
-
-@item -h,--help
-Show a summary of usage.
-
-@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 -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)
-
-@item --ps
-Generate PostScript.
-
-@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
-@example
--dresolution=110
-@end example
-
-@item --pdf
-Generate PDF. This implies @code{--ps}.
-
-
-
-@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
-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 @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 @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:
-
-@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, @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}.
-
-@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 appear 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.
-
-@item -V,--verbose
-Be verbose: show full paths of all files read, and give timing
-information.
-
-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
-
-@node Environment variables
-@subsection Environment variables
-
-
-@cindex LANG
-@cindex LILYPOND_DATADIR
-
-@command{lilypond} recognizes the following environment variables:
-@table @code
-@item LILYPOND_DATADIR
-This specifies a directory where locale messages and
-data files will be looked up by default. The directory should contain
-subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
-
-@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
-
-
-@node Error messages
-@section Error messages
-
-@cindex error messages
-Different error messages can appear while compiling a file:
-
-@table @emph
-
-@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.
-
-@item 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.
-
-@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.
-
-@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.
-
-@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 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 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.
-
-
-
projects / lilypond.git / blobdiff