* Documentation/user/global.itely (Extracting fragments of

[lilypond.git] / Documentation / user / global.itely

diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index 4449a5418739781159fd6293b91ccc8289fbd9a9..974d8c881592726a93f5e416ac73eda319a1ddbf 100644 (file)
--- a/Documentation/user/global.itely
+++ b/Documentation/user/global.itely
@@ -29,6 +29,7 @@ these files end with ``@code{.ly}''.
 @menu
 * File structure (introduction)::  
 * Multiple scores in a book::   
+* Extracting fragments of notation::  
 * File structure::              
 * A single music expression::   
 * Including LilyPond files::    
@@ -144,6 +145,44 @@ the top of the file is inserted.
 @}
 @end example
 
+@node Extracting fragments of notation
+@subsection Extracting fragments of notation
+
+It is possible to quote small fragments of a large score directly from
+the output. This can be compared to clipping a piece of a paper score
+with scissors.
+
+This is done by definining the measures that need to be cut out
+separately. For example, including the following definition
+
+
+@verbatim
+\layout {
+  clip-regions
+  = #(list
+      (cons
+       (make-rhythmic-location 5 1 2)
+       (make-rhythmic-location 7 3 4)))
+}       
+@end verbatim
+
+@noindent
+will extract a fragment starting halfway the fifth measure, ending in
+the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note
+in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
+
+More clip regions can be defined by adding more pairs of
+rhythmic-locations to the list. 
+
+In order to use this feature, LilyPond must be invoked with
+@code{-dclip-systems}. The clips are output as EPS files, and are
+converted to PDF and PNG if these formats are switched on as well.
+
+For more information on output formats, see @ref{Invoking lilypond}.
+
+@seealso
+
+Examples: @inputfileref{input/regression/clip-systems.ly}
 
 
 @node File structure
@@ -370,6 +409,8 @@ by using a Unicode-aware editor and saving the file with utf-8 encoding.  Most
 popular modern editors have utf-8 support, for example, vim, Emacs,
 jEdit, and GEdit do.
 
+@c  Currently not working
+@ignore
 Depending on the fonts installed, the following fragment shows Hebrew
 and Cyrillic lyrics,
 
@@ -377,7 +418,7 @@ and Cyrillic lyrics,
 @cindex Hebrew
 @cindex ASCII, non
 
-@lilypondfile[fontload]{utf-8.ly}
+@li lypondfile[fontload]{utf-8.ly}
 
 The @TeX{} backend does not handle encoding specially at all.  Strings
 in the input are put in the output as-is.  Extents of text items in the
@@ -400,6 +441,8 @@ Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
 interpreting non-ASCII strings.
 
+@end ignore
+
 To use a Unicode escape sequence, use
 
 @example