X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Frunning.itely;h=01784ab75ab750ac588833982d77c9d254097fe6;hb=0b58c7d1f556ce0a62c3bcdce172e0f4fe9d19f0;hp=b9d5b22601f8548b698065b87ed10e4a78d3f51c;hpb=223b1ac16b1b80cd1226eed24968bf7c49c24ec8;p=lilypond.git diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index b9d5b22601..01784ab75a 100644 --- a/Documentation/usage/running.itely +++ b/Documentation/usage/running.itely @@ -52,14 +52,14 @@ scope of this manual; please consult other documentation on this topic if you are unfamiliar with the command-line. @menu -* Invoking lilypond:: +* Invoking LilyPond:: * Basic command line options for LilyPond:: * Advanced command line options for LilyPond:: * Environment variables:: * LilyPond in chroot jail:: @end menu -@node Invoking lilypond +@node Invoking LilyPond @unnumberedsubsec Invoking @command{lilypond} The @command{lilypond} executable may be called as follows from @@ -69,7 +69,6 @@ the command line. 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}. @@ -98,28 +97,74 @@ will output @var{base}@file{-violin.pdf} and @var{base}@file{-cello-1.pdf}. -@unnumberedsubsubsec Standard shell commands +@unnumberedsubsubsec Using LilyPond with standard shell features -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: +Since LilyPond is a command line application, features of the @q{shell} +used for calling LilyPond can also be put to good use. -@itemize +For example: -@item -@code{lilypond file.ly 1>stdout.log} to redirect normal output +@example +lilypond *.ly +@end example -@item -@code{lilypond file.ly 2>stderr.log} to redirect error messages +@noindent +will process all LilyPond files in the current directory. -@item -@code{lilypond file.ly &>all.log} to redirect all output +Redirecting the console output (e.g. to a file) may also be useful: -@end itemize +@example +lilypond file.ly 1> stdout.txt -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. +lilypond file.ly 2> stderr.txt + +lilypond file.ly &> all.txt +@end example + +@noindent +Redirects @q{normal} output, @q{errors} only or @q{everything}, +respectively, to a text file. Consult the documentation for your +particular shell, Command (Windows), Terminal or Console +applications (MacOS X) to see if output redirection is supported or if +the syntax is different. + +The following example searches and processes all input files in the +current directory and all directories below it recursively. The output +files will be located in the same directory that the command was run in, +rather than in the same directories as the original input files. + +@example +find . -name '*.ly' -exec lilypond '@{@}' \; +@end example + +@noindent +This should also work for MacOS@tie{}X users. + +A Windows user would run; + +@example +forfiles /s /M *.ly /c "cmd /c lilypond @@file" +@end example + +@noindent +entering these commands in a @code{command prompt} usually found under +@code{Start > Accessories > Command Prompt} or for version 8 users, +by typing in the search window @q{command prompt}. + +Alternatively, an explicit path to the top-level of your folder +containing all the sub-folders that have input files in them can be +stated using the @code{/p} option; + +@example +forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c lilypond @@file" +@end example + +If there are spaces in the path to the top-level folder, then the whole +path needs to be inside double quotes; + +@example +forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c lilypond @@file" +@end example @node Basic command line options for LilyPond @@ -419,7 +464,10 @@ files in the SVG backend. @item @code{clip-systems} @tab @code{#f} -@tab Generate cut-out snippets of a score. +@tab Extract music fragments out of a score. This requires that the +@code{clip-regions} function has been defined within the @code{\layout} +block. See @ruser{Extracting fragments of music}. No fragments are +extracted though if used with the @option{-dno-print-pages} option. @item @code{datadir} @tab @@ -915,6 +963,13 @@ 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. +Please note that diagnostics can be triggered at any point during the +many stages of processing. For example if there are parts of the input +that are processed multiple times (i.e. in midi and layout output), or +if the same music variable is used in multiple contexts the same message +may appear several times. Diagnostics produced at a @q{late} stage (i.e +bar checks) might also be issued multiple times. + More information about errors is given in @ref{Common errors}. @@ -933,6 +988,7 @@ are easily handled. * Error message FT_Get_Glyph_Name:: * Warning staff affinities should only decrease:: * Error message unexpected new:: +* Warning ignoring too many clashing note columns:: @end menu @node Music runs off the page @@ -994,30 +1050,6 @@ 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 -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' { c4 d e f } -} -@end lilypond - -Explicitly instantiating the @code{Voice} context fixes the -problem: - -@lilypond[quote,verbatim] -\new Voice { - \repeat unfold 2 { - \relative c' { c4 d e f } - } -} -@end lilypond - - @node Error message Unbound variable % @unnumberedsubsec Error message Unbound variable % @@ -1040,6 +1072,7 @@ 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 @@ -1103,3 +1136,37 @@ staves are introduced in parallel, i.e. simultaneously: >> } @end lilypond + +@node Warning ignoring too many clashing note columns +@unnumberedsubsec Warning ignoring too many clashing note columns + +If notes from two different voices with stems in the same direction +occur at the same musical moment, but the voices have no +voice-specific shifts specified, the warning message +@samp{warning: ignoring too many clashing note columns} will appear +when compiling the LilyPond file. This warning will appear even when +the notes have no visible stems, e.g. whole notes, if the stems for +shorter notes at the same pitch would be in the same direction. + +Remember that the stem direction depends on the position of the +note on the staff unless the stem direction is specified, for example +by using @code{\voiceOne}, etc. In this case the warning will appear +only when the stems happen to be in the same direction, i.e. when the +notes are in the same half of the staff. + +By placing the notes in voices with stem directions and shifts +specified, for example by using @code{\voiceOne}, etc., these warnings +may be avoided. + +Notes in higher numbered voices, @code{\voiceThree} etc., are +automatically shifted to avoid clashing note columns. This causes a +visible shift for notes with stems, but whole notes are not visibly +shifted unless an actual clash of the note heads occurs, or when the +voices cross over from their natural order (when @code{\voiceThree} +is higher than @code{\voiceOne}, etc.) + +@seealso +@rlearning{Explicitly instantiating voices}, +@rlearning{Real music example}, +@ruser{Single-staff polyphony}, +@ruser{Collision resolution}.