X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fusage%2Frunning.itely;h=147bc84c6720737698a69ed46e9f079af004c0dc;hb=a066a93ee74edebb9d238a1bac93c3bc7e8e6e4a;hp=263a7e8c9b76a8489a3a496cc5480c679f82d4fa;hpb=199c0c3722ab9920ee941d7086e81b1f887b14bf;p=lilypond.git diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index 263a7e8c9b..147bc84c67 100644 --- a/Documentation/usage/running.itely +++ b/Documentation/usage/running.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.12.0" +@c \version "2.14.0" @node Running lilypond @@ -97,6 +97,30 @@ will output @var{base}@file{-violin.pdf} and @var{base}@file{-cello-1.pdf}. +@unnumberedsubsubsec Standard shell commands + +If your shell (i.e. command window) supports normal redirects, +then you might find it useful to use the following commands to +redirect console output to a file: + +@itemize + +@item +@code{lilypond file.ly 1>stdout.log} to redirect normal output + +@item +@code{lilypond file.ly 2>stderr.log} to redirect error messages + +@item +@code{lilypond file.ly &>all.log} to redirect all output + +@end itemize + +Consult the documentation for your shell to see if it supports these +options, or if the syntax is different. Note that these are shell +commands and have nothing to do with lilypond. + + @node Command line options for lilypond @unnumberedsubsec Command line options for @command{lilypond} @@ -111,7 +135,7 @@ The following options are supported: @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 +Multiple @option{-e} options may be given, they will be evaluated sequentially. The expression will be evaluated in the @code{guile-user} module, so @@ -162,7 +186,7 @@ Here are a few interesting options. @table @samp @item help -Running @code{lilypond -dhelp} will print all of the @code{-d} options +Running @code{lilypond -dhelp} will print all of the @option{-d} options available. @cindex paper-size, command line @@ -183,8 +207,8 @@ Note that the string must be enclosed in escaped quotes ( @code{\"} ). 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 +@option{--safe} or the @option{--jail} option @b{MUST} be passed. The +@option{--safe} option will prevent inline Scheme code from wreaking havoc, for example @quotation @@ -196,10 +220,10 @@ havoc, for example @end verbatim @end quotation -The @code{-dsafe} option works by evaluating in-line Scheme +The @option{-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}. +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. @@ -207,14 +231,14 @@ 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 +@option{-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 +compiled. The @option{--jail} is a more secure alternative, but requires more work to set up. @cindex output format, setting @@ -262,7 +286,7 @@ This mode is used by default by @command{lilypond-book}. 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}. + do not output a printed score; has the same effect as @option{-dno-print-pages}. @end table Example: @code{lilypond -dbackend=svg @var{filename}.ly} @@ -275,9 +299,19 @@ first system of every @code{\bookpart} will appear in the output. The @code{ps}, @code{eps}, and @code{svg} backends support this option. +@item gui +Runs silently and redirect all output to a log file. + +Note to Windows users: By default @code{lilypond.exe} outputs all +progress information to the command window, @code{lilypond-windows.exe} +does not and returns a prompt, with no progress information, immediately +at the command line. The @option{-dgui} option can be used in this case +to redirect output to a log file. + + @item print-pages -Generate the full pages, the default. @code{-dno-print-pages} is -useful in combination with @code{-dpreview}. +Generate the full pages, the default. @option{-dno-print-pages} is +useful in combination with @option{-dpreview}. @end table @@ -301,6 +335,35 @@ found the search will continue in subsequent directories. @item -i,--init=@var{file} Set init file to @var{file} (default: @file{init.ly}). +@cindex loglevel +@cindex output verbosity, setting + +@item -l,--loglevel=@var{LEVEL} +Set the verbosity of the console output to @var{LEVEL}. Possible values are: +@table @code +@item NONE +No output at all, not even error messages. + +@item ERROR +Only error messages, no warnings or progress messages. + +@item WARN +Warnings and error messages, no progress. + +@item BASIC_PROGRESS +Basic progress messages (success), warnings and errors. + +@item PROGRESS +All progress messages, warnings and errors. + +@item INFO (default) +Progress messages, warnings, errors and further execution information. + +@item DEBUG +All possible messages, including verbose debug output. +@end table + + @cindex folder, directing output to @cindex output filename, setting @@ -320,7 +383,7 @@ 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 +@option{--ps}. The resolution in DPI of the image may be set with @example -dresolution=110 @end example @@ -328,24 +391,24 @@ Generate pictures of each page, in PNG format. This implies @cindex Portable Document Format (PDF) output @item --pdf -Generate PDF. This implies @code{--ps}. +Generate PDF. This implies @option{--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 +The @option{--jail} option provides a more flexible alternative to +@option{--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 +The @option{--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 +@option{--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 @@ -421,11 +484,15 @@ subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. @item LANG This selects the language for the warning messages. +@item LILYPOND_LOGLEVEL +The default loglevel. If LilyPond is called without an explicit loglevel (i.e. +no @option{--loglevel} command line option), this value is used. + @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}. +A variable, as a percentage, that tunes memory management +behavior. A higher values means the program uses more memory, a +smaller value means more CPU time is used. The default value is +@code{70}. @end table @@ -483,7 +550,10 @@ You can use @code{sed} to create the necessary copy commands for a given executable: @example -for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done +for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; \ + do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& \ + cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \ + \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done @end example @end itemize @@ -524,18 +594,25 @@ cp -L /usr/bin/convert /usr/bin/gs usr/bin cp -L /usr/share/fonts/truetype usr/share/fonts # Now the library copying magic -for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh" "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done | sh -s +for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh" \ + "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \ + \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed \ + 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' \ + | sed '/.*=>.*/d'; done | sh -s # The shared files for ghostscript... cp -L -r /usr/share/ghostscript usr/share # The shared files for ImageMagick cp -L -r /usr/lib/ImageMagick* usr/lib -### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome, you should be able to run: -### Note that /$lilyprefix/bin/lilypond is a script, which sets the LD_LIBRARY_PATH - this is crucial +### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome, +### you should be able to run: +### Note that /$lilyprefix/bin/lilypond is a script, which sets the +### LD_LIBRARY_PATH - this is crucial /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly @end example +@c " keep quote signs balanced for context-sensitive editors @node Error messages @section Error messages @@ -568,8 +645,8 @@ happens rarely. The most usual cause is misinstalled fonts. @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 +interpreter. If running with the verbose option (@option{-V} or +@option{--verbose}) then a call trace of the offending function call is printed. @item Programming error @@ -628,6 +705,7 @@ are easily handled. * Apparent error in ../ly/init.ly:: * Error message Unbound variable %:: * Error message FT_Get_Glyph_Name:: +* Warning staff affinities should only decrease:: @end menu @node Music runs off the page @@ -717,7 +795,7 @@ problem: @unnumberedsubsec Apparent error in @code{../ly/init.ly} Various obscure error messages may appear about syntax errors in -@code{../ly/init.ly} if the input file is not correctly formed, +@file{../ly/init.ly} if the input file is not correctly formed, for example, if it does not contain correctly matched braces or quote signs. @@ -733,7 +811,7 @@ of a lyrics block and the terminating brace, (@code{@}}). Without this separation the brace is taken to be part of the syllable. It is always advisable to ensure there is white space before and after @emph{every} brace. For the importance of this when using lyrics, -see @ruser{Lyrics explained}. +see @ruser{Entering lyrics}. This error message can also appear if a terminating quote sign, (@code{"}), is omitted. In this case an accompanying error message @@ -761,4 +839,18 @@ an input file contains a non-ASCII character and was not saved in UTF-8 encoding. For details, see @ruser{Text encoding}. +@node Warning staff affinities should only decrease +@unnumberedsubsec Warning staff affinities should only decrease +This warning can appear if there are no staves in the printed +output, for example if there are just a @code{ChordName} context +and a @code{Lyrics} context as in a lead sheet. The warning +messages can be avoided by making one of the contexts behave as a +staff by inserting +@example +\override VerticalAxisGroup #'staff-affinity = ##f +@end example + +@noindent +at its start. For details, see @qq{Spacing of non-staff lines} in +@ruser{Flexible vertical spacing within systems}.