X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finvoking.itely;h=b4157bde317b5e4b692448835b47e73c6385816b;hb=3ae319d608009abcb39852f3ffa8e2974710db86;hp=cac60b65940b88ccd9796863b4256a5bea9b8e14;hpb=eb9165dc3bb9679dac24a9ce3ce9a33bd36a2bda;p=lilypond.git diff --git a/Documentation/user/invoking.itely b/Documentation/user/invoking.itely index cac60b6594..b4157bde31 100644 --- a/Documentation/user/invoking.itely +++ b/Documentation/user/invoking.itely @@ -8,9 +8,9 @@ This chapter details the technicalities of running LilyPond. @menu * Invoking lilypond:: * Error messages:: +* Updating files with convert-ly:: * Reporting bugs:: * Editor support:: -* Invoking lilypond-latex:: @end menu @node Invoking lilypond @@ -56,7 +56,7 @@ some internal variables. Use @code{-e '(ly:option-usage)'} for more information. @item -f,--format=@var{format} -which formats should be written. Choices are @code{svg}, @code{ps}, +which formats should be written. Choices are @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}. @item -b,--backend=@var{format} @@ -68,10 +68,22 @@ for @TeX{} output, to be processed with La@TeX{}. If present, the file @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. +extents of strings of text. @item ps - for PostScript + for PostScript. @cindex PostScript output + + 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 lilypond-book. + @item svg for SVG (Scalable Vector Graphics) @cindex SVG (Scalable Vector Graphics) @@ -82,6 +94,21 @@ extents of strings of text. @cindex output format, setting +@item -d,--define-default=@var{var}=@var{val} +This defines an internal variable @var{var} as the Scheme value +@var{val}. + +Supported values include: +@table @code +@item resolution +set PNG resolution +@item preview-include-book-title +include book-titles in preview +@end table + +These settings are returned when calling +@code{(ly:get-option 'command-line-settings)} from Scheme. + @item -h,--help Show a summary of usage. @@ -121,6 +148,11 @@ Do not generate the full pages. Useful in combination with @item -s,--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 + When LilyPond formatting is available through a web server, the @code{--safe} @b{MUST} be passed. This will prevent inline Scheme code from wreaking havoc, for example @@ -145,12 +177,76 @@ disables the use of backslashes in @TeX{} strings. In @code{--safe} mode, it is not possible to import LilyPond variables into Scheme. -@code{--safe} does @emph{not} detect resource overuse. It is still +@code{--safe} 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. +Note that @code{--safe} will prevent many useful LilyPond snippets from +being compiled. For a softer but secure alternative you can use the +@code{--jail} option. + + +@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} +Run LilyPond in a 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 +@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 +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, @samp{lily}/@samp{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 apper 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. @@ -305,6 +401,122 @@ 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} + +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. + +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 + +@example +convert-ly -e myfile.ly +@end example + +If there are no changes to myfile.ly and file called myfile.ly.NEW +is created, then myfile.ly is already updated. + +To upgrade LilyPond fragments in texinfo files, use + +@example +convert-ly --from=... --to=... --no-version *.itely +@end example + +To upgrade many files at once, combine @code{convert-ly} with +standard unix commands. This example will upgrade all @code{.ly} +files in the current directory + +@example +for f in *.ly; do convert-ly -e $f; done; +@end example + +In general, the program is invoked as follows: + +@example +convert-ly [@var{option}]@dots{} @var{file}@dots{} +@end example + + +The following options can be given: + +@table @code +@item -e,--edit +Do an inline edit of the input file. Overrides @code{--output}. + +@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. + +@item -o,--output=@var{file} +Set the output file to write. + +@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. + +@item -h, --help +Print usage help. +@end table + +@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. + +@refbugs + +Not all language changes are handled. Only one output option can be +specified. + + +@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 +Feb 14, 2005 + +http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain +@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. + +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 occurencies 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. Only very simple cases are fixed. +2.0->2.2: + Doesn't handle \partcombine + Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas. +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. +@end verbatim + + @node Reporting bugs @section Reporting bugs @@ -318,11 +530,15 @@ reproduce the problem. Make it small, so we can easily debug the problem. Don't forget to tell which version of LilyPond you use! Send the report to @email{bug-lilypond@@gnu.org}. +@ignore +@c the bug database is not up to date enough. + When you've found a bug, have a look at our -@uref{http://@/lilypond@/.org/@/doc/@/v2.3/@/bugs/,bug database} to see if +@uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if it has already been reported. You could also try to do a few searches on the mailing list for the bug. Sometimes the bug will have already been reported and a fix or workaround is already known. +@end ignore Here is an example of a good bug report: @@ -332,14 +548,14 @@ following example, the accidental touches the note head. Using Mac OSX 10.3.5, fink package lilypond-unstable -\version "2.3.22" +\version "2.5.18" \relative c''@{ a4 b cis d @} @end example @lilypond[quote] -\version "2.3.22" +\version "2.5.18" \relative c''{ \override Accidental #'extra-offset = #'(1.0 . 0) a4 b cis d @@ -366,7 +582,7 @@ 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{../../../topdocs/out-www/INSTALL.html,installation instructions}. +@uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}. @end ifhtml @ifnothtml installation instructions. @@ -377,7 +593,7 @@ installation instructions. 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{../../../topdocs/out-www/INSTALL.html,installation instructions}. +@uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}. @end ifhtml @ifnothtml installation instructions. @@ -386,7 +602,7 @@ installation instructions. @item JEdit -The @uref{http://@/www@/.jedit@/.org/,jEdit} editor has a LilyPond plugin. +The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin. This plugin includes a DVI viewer, integrated help and viewing via GhostScript. It can be installed by doing @key{Plugins > Plugin Manager}, and selecting @code{LilyTool} from the @key{Install} tab. @@ -397,127 +613,3 @@ 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 Invoking lilypond-latex -@section Invoking lilypond-latex - -Before LilyPond 2.4, the @code{lilypond} program only generated music -notation. Titles and page layout was done in a separate wrapper -program. For compatibility with older files, this wrapper program has -been retained as @code{lilypond-latex}. It uses the LilyPond program -and La@TeX{} to create a nicely titled piece of sheet music. Use of -this program is only necessary if the input file contains special -La@TeX{} options or formatting codes in markup texts. - -The @code{lilypond-latex} wrapper is invoked from the command-line as -follows -@example -@code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{} -@end example - -To have @code{lilypond-latex} read from stdin, use a dash (@code{-}) for -@var{file}. The program supports the following options. - -@cindex stdin, reading - -@table @code -@item -k,--keep -Keep the temporary directory with all output files. The temporary -directory is created in the current directory as @code{@code{lilypond}.dir}. - -@item -h,--help -Print usage help. - -@item -I,--include=@var{dir} -Add @var{dir} to LilyPond's include path. - -@item -o,--output=@var{file} -Generate output to @var{file}. The extension of @var{file} is ignored. - -@item --png -Also generate pictures of each page, in PNG format. - -@item --preview -Also generate a picture of the first system of the score. - -@cindex preview -@cindex picture -@cindex bitmap -@cindex pixmap -@cindex thumbnail -@cindex screen shot - -@item -s,--set=@var{key}=@var{val} -Add @var{key}= @var{val} to the settings, overriding those specified -in the files. Possible keys: @code{language}, @code{latexheaders}, -@code{latexpackages}, @code{latexoptions}, @code{papersize}, -@code{linewidth}, @code{orientation}, -@code{textheight}. - -@item -v,--version -Show version information. - -@item -V,--verbose -Be verbose. This prints out commands as they are executed, and more -information about the formatting process is printed. - -@item --debug -Print even more information. This is useful when generating bug reports. - -@item -w,--warranty -Show the warranty with which GNU LilyPond comes. (It comes with -@strong{NO WARRANTY}!) -@end table - - -@subsection Additional parameters - -The @code{lilypond} program responds to several parameters specified -in a @code{\layout} section of the input file. They can be overridden -by supplying a @code{--set} command line option. - -@table @code -@item language -Specify La@TeX{} language: the @code{babel} package will be -included. Default: unset. - -Read from the @code{\header} block. - -@item latexheaders -Specify additional La@TeX{} header files. -Normally read from the @code{\header} block. Default value: empty. - -@item latexpackages -Specify additional La@TeX{} package files. This works cumulative, -so you can add multiple packages using multiple @code{-s=latexpackages} options. -Normally read from the @code{\header} block. Default value: -@code{geometry}. - -@item latexoptions -Specify additional options for the La@TeX{} -@code{\documentclass}. You can put any valid value here. This was -designed to allow @code{lilypond} to produce output for double-sided -paper, with balanced margins and page numbers on alternating sides. To -achieve this specify @code{twoside}. - -@item orientation -Set orientation. Choices are @code{portrait} or @code{landscape}. Is -read from the @code{\layout} block, if set. - -@item textheight -The vertical extension of the music on the page. It is normally -calculated automatically, based on the paper size. - -@item linewidth -The music line width. It is normally read from the @code{\layout} -block. - -@item papersize -The paper size (as a name, e.g., @code{a4}). It is normally read from -the @code{\layout} block. - -@item fontenc -The font encoding, should be set identical to the @code{font-encoding} -property in the score. -@end table