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

notation): new node, about clip systems.

* Documentation/user/lilypond-book.itely (Many quotes of a large
score): ref to clip systems.

diff --git a/ChangeLog b/ChangeLog
index fdf144c6e851b6b5f80a6f19a282f1f22cff50f0..90d3a66610f71ae74a7285900412034c3bce94d3 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2006-10-20  Han-Wen Nienhuys  <hanwen@lilypond.org>
 
+       * Documentation/user/global.itely (Extracting fragments of
+       notation): new node, about clip systems.
+
+       * Documentation/user/lilypond-book.itely (Many quotes of a large
+       score): ref to clip systems.
+
        * Documentation/user/instrument-notation.itely (Entering lyrics):
        add note about lyric ties and required font.
 

diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index e6150cfb87a92a482a55e0f46c944e7ebc7322ef..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

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index 89a7af3af0efb93b3bc72ee3eee764a9f9e06f37..d81d3ee9dd10f3b8ce3927e41c6120ec23cfcbbc 100644 (file)
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -38,6 +38,7 @@ This procedure may be applied to La@TeX{}, HTML or Texinfo documents.
 * Music fragment options::      
 * Invoking lilypond-book::      
 * Filename extensions::         
+* Many quotes of a large score::  
 * Inserting LilyPond output into other programs::  
 @end menu
 
@@ -764,16 +765,20 @@ output format based on the input filename's extension.
 @end multitable
 @end quotation
 
+@node Many quotes of a large score
+@section Many quotes of a large score
+
+If you need to quote many fragments of a large score, you can also use
+the clip systems feature, see @ref{Extracting fragments of notation}.
 
 @node Inserting LilyPond output into other programs
 @section Inserting LilyPond output into other programs
 
 To insert LilyPond output in other programs, use @code{lilypond}
 instead of @code{lilypond-book}.  Each example must be created
-individually and added to the document; consult the
-documentation for that program.  Most programs will be able
-to insert lilypond output in @file{PNG}, @file{EPS}, or @file{PDF}
-formats.
+individually and added to the document; consult the documentation for
+that program.  Most programs will be able to insert lilypond output in
+@file{PNG}, @file{EPS}, or @file{PDF} formats.
 
 To reduce the white space around your lilypond score, use
 the following options