X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;fp=Documentation%2Fuser%2Frunning.itely;h=0000000000000000000000000000000000000000;hb=e90f0536f9be39ada0bef0aeb0d275dec3b2fb5b;hp=1864615a5279c27ad58698877b8e5c24cdbc319e;hpb=a8c9e8a7ca320ab0df5fd32e717fd62cd7635ce6;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely deleted file mode 100644 index 1864615a52..0000000000 --- a/Documentation/user/running.itely +++ /dev/null @@ -1,686 +0,0 @@ -@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. - - -