Doc: Clarified how to use clip-systems option

[lilypond.git] / Documentation / usage / running.itely

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index b9d5b22601f8548b698065b87ed10e4a78d3f51c..01784ab75ab750ac588833982d77c9d254097fe6 100644 (file)
--- 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
 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
 
 * 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
 @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
 
 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}.
 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}.
 
 
 @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
 
 
 @node Basic command line options for LilyPond


@@ -419,7 +464,10 @@ files in the SVG backend.
 
 @item @code{clip-systems}
 @tab @code{#f}
 
 @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
 
 @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.
 
 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}.
 
 
 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::
 * 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
 @end menu
 
 @node Music runs off the page


@@ -994,30 +1050,6 @@ correct code to color all note heads red is
 }
 @end lilypond
 
 }
 @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 %
 
 @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
 
 @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
 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
   >>
 }
 @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}.