X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Frunning.itely;h=82772da6d69c9b1664ecff31b730adff97c7dfd3;hb=10bd5cc93870ac4b884b8cb938cfc6a19c768097;hp=93c0c3a3a78aee2769c4b6d7b56499d230d5e112;hpb=a1880937e621d12d2bb2827f27aac6361e0a2ac9;p=lilypond.git diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index 93c0c3a3a7..82772da6d6 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.13.36" @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} @@ -231,7 +255,7 @@ the output format to use for the back-end. Choices for @code{format} are @item eps -@cindex Postscript, encapulated +@cindex Postscript, encapsulated @cindex EPS (Encapsulated PostScript) for encapsulated PostScript. This dumps every page (system) as a separate @@ -289,17 +313,27 @@ 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 --include, -I=@var{directory} +Add @var{directory} to the search path for input files. + +Multiple -I options may be given. The search will start in the +first defined directory, and if the file to be included is not +found the search will continue in subsequent directories. @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) +@cindex folder, directing output to +@cindex output filename, setting + +@item -o,--output=@var{FILE} or @var{FOLDER} +Set the default output file to @var{FILE} or, if a folder with +that name exists, direct the output to @var{FOLDER}, taking the +file name from the input file. The appropriate suffix will be +added (e.g. @code{.pdf} for pdf) in both cases. + @cindex PostScript output @@ -389,7 +423,7 @@ 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 +Show the warranty with which GNU LilyPond comes. (It comes with @strong{NO WARRANTY}!) @end table @@ -473,7 +507,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 @@ -514,18 +551,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 @@ -618,6 +662,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 @@ -649,17 +694,17 @@ line to break. For details, see @ruser{Bar lines}. @node An extra staff appears @unnumberedsubsec An extra staff appears -If contexts are not created explicitly with @code{\new} they will be -silently created as soon as a command is encountered which cannot -be applied to an existing context. In simple scores the automatic -creation of contexts is useful, and most of the examples in the -LilyPond manuals take advantage of this simplification. But -occasionally the silent creation of contexts can give rise to -unexpected new staves or scores. For example, it might be expected -that the following code would cause all note heads within the -following staff to be colored red, but in fact it results in two -staves with the note heads remaining the default black in the lower -staff. +If contexts are not created explicitly with @code{\new} or +@code{\context}, they will be silently created as soon as a +command is encountered which cannot be applied to an existing +context. In simple scores the automatic creation of contexts is +useful, and most of the examples in the LilyPond manuals take +advantage of this simplification. But occasionally the silent +creation of contexts can give rise to unexpected new staves or +scores. For example, it might be expected that the following code +would cause all note heads within the following staff to be +colored red, but in fact it results in two staves with the note +heads remaining the default black in the lower staff. @lilypond[quote,verbatim,relative=2] \override Staff.NoteHead #'color = #red @@ -680,23 +725,25 @@ correct code to color all note heads red is @end lilypond As a second example, if a @code{\relative} command is placed inside -a @code{\repeat} command two staves result, the second offset from +a @code{\repeat} command, two staves result, the second offset from the first, because the @code{\repeat} command generates two @code{\relative} blocks, which each implicitly create @code{Staff} and @code{Voice} blocks. @lilypond[quote,verbatim] \repeat unfold 2 { - \relative c' { c d e f } + \relative c' { c4 d e f } } @end lilypond -The correct way is to reverse the @code{\repeat} and -@code{\relative} commands, like this: +Explicitly instantiating the @code{Voice} context fixes the +problem: @lilypond[quote,verbatim] -\relative c' { - \repeat unfold 2 { c d e f } +\new Voice { + \repeat unfold 2 { + \relative c' { c4 d e f } + } } @end lilypond @@ -721,7 +768,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 @@ -749,4 +796,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{Vertical spacing inside a system}.