From e9b7aec9e41b63d6a35936c840fb9aa387a61e0f Mon Sep 17 00:00:00 2001
From: Han-Wen Nienhuys <hanwen@xs4all.nl>
Date: Fri, 20 Oct 2006 20:48:41 +0000
Subject: [PATCH] * 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.
---
 ChangeLog                              |  6 ++++
 Documentation/user/global.itely        | 39 ++++++++++++++++++++++++++
 Documentation/user/lilypond-book.itely | 13 ++++++---
 3 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fdf144c6e8..90d3a66610 100644
--- 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 e6150cfb87..974d8c8815 100644
--- 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 89a7af3af0..d81d3ee9dd 100644
--- 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
-- 
2.39.2