X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;h=33395322b14f347e05950c60a089588b2175d3c7;hb=fb56252985ed1037637874f1b22f3d84b238a619;hp=0b992069c119cda3091e249d79fd87630f9c39d5;hpb=651180d1740e69825d07eb83e1454b3cf534b734;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely index 0b992069c1..33395322b1 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/running.itely @@ -7,6 +7,8 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.11.38" + @node Running LilyPond @chapter Running LilyPond @@ -15,17 +17,17 @@ This chapter details the technicalities of running LilyPond. @menu * Normal usage:: -* Command-line usage:: -* Error messages:: -* Updating files with convert-ly:: -* Reporting bugs:: +* 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 @ruser{First steps} if +Most users run LilyPond through a GUI; see @rlearning{First steps} if you have not read this already. @@ -39,15 +41,21 @@ 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}; OSX users might be more familiar with the terms -@q{terminal} or @q{console}. OSX users should also consult @ref{MacOS X +@q{command shell}; MacOS@tie{}X users might be more familiar with the terms +@q{terminal} or @q{console}. They should also consult @ref{MacOS X on the command-line}. 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:: +* Environment variables:: +@end menu +@node Invoking lilypond @subsection Invoking lilypond @cindex Invoking LilyPond @@ -56,7 +64,7 @@ if you are unfamiliar with the 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{} @@ -77,13 +85,13 @@ GUILE is not reset after processing a @code{.ly} file, so be careful not to change any system defaults from within Scheme.} In addition, the value of @code{output-suffix} will be inserted between -the basename and the number. An input file containing +the basename and the number. An input file containing @example #(define output-suffix "violin") -\book @{ @dots{} @} +\book @{ @dots{} @} #(define output-suffix "cello") -\book @{ @dots{} @} +\book @{ @dots{} @} @end example @noindent @@ -91,7 +99,7 @@ will output @var{base}@file{-violin.ps} and @var{base}@file{-cello-1.ps}. - +@node Command line options @subsection Command line options The following options are supported: @@ -130,7 +138,7 @@ Example: @code{lilypond -fpng 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 @@ -153,7 +161,7 @@ Running @code{lilypond -dhelp} will print all of the @code{-d} options available. @item paper-size -This option sets the default paper-size, +This option sets the default paper-size, @example -dpaper-size=\"letter\" @end example @@ -232,7 +240,7 @@ This mode is used by default by lilypond-book. @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} + 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/}. @item scm @@ -294,24 +302,24 @@ Generate PDF. This implies @code{--ps}. @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 @@ -324,7 +332,7 @@ 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 +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}. @@ -364,14 +372,14 @@ 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 -@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 @@ -383,9 +391,9 @@ 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 +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 @@ -485,8 +493,8 @@ convert-ly -e myfile.ly @end example @noindent -MacOS X users may execute this command under the menu entry -@samp{Compile > Update syntax}. +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. @@ -510,7 +518,7 @@ convert-ly --from=... --to=... -s @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 @@ -559,12 +567,12 @@ Print usage help. @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. @verbatim -There are a few things that the convert-ly cannot handle. Here's a list +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 @@ -573,12 +581,12 @@ 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") @@ -625,7 +633,7 @@ converted. @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} @@ -634,7 +642,7 @@ bug by following the directions on @uref{http://lilypond.org/web/devel/participating/bugs} -Please construct submit @ruser{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.