Doc: Clarified how to use clip-systems option

Issue 4219

Improved explanation of how to extract music
fragments in the NR and the corresponding
clip-systems option in Usage.

Added some @cindex and @funindex as well as some
@seealso.

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index 31bf09fb0736b4d1dae531fb21ab5a5005437558..896caf2de2f0066035ce87a480db26c0d60549b3 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -2514,40 +2514,54 @@ Installed Files:
 * Replacing the notation font::
 @end menu
 
+@funindex clip-regions
+@cindex Fragments, music
+@cindex Music fragments
+
 @node Extracting fragments of music
 @subsection Extracting fragments of music
 
-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 defining the measures that need to be cut out
-separately.  For example, including the following definition
+It is possible to output one or more fragments of a score by defining
+the explicit location of the music to be extracted within the
+@code{\layout} block of the the input file using the @code{clip-regions}
+function, and then running LilyPond with the @option{-dclip-systems}
+option;
 
-
-@verbatim
-\layout {
+@example
+\layout @{
   clip-regions
   = #(list
       (cons
        (make-rhythmic-location 5 1 2)
        (make-rhythmic-location 7 3 4)))
-}
-@end verbatim
+@}
+@end example
 
 @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.
+This example will extract a single fragment of the input file
+@emph{starting} after a half-note duration in fifth measure
+(@code{5 1 2}) and @emph{ending} after three, quarter notes in the
+seventh measure (@code{7 3 4}).
+
+Additional fragments can be extracted by adding more pairs of
+@code{make-rhythmic-location} entries to the @code{clip-regions} list in
+the @code{\layout} block.
+
+By default, each music fragment will be output as a separate @code{EPS}
+file, but other formats such as @code{PDF} or @code{PNG} can also be
+created if required.  The extracted music is output as if had been
+literally @q{cut} from the original printed score so if a fragment runs
+over one or more lines, a separate ouput file for each line will be
+generated.
+
+@seealso
+Notation Reference:
+@ref{The layout block}.
 
-More clip regions can be defined by adding more pairs of
-rhythmic-locations to the list.
+Application Usage
+@rprogram{Command-line usage}.
 
-In order to use this feature, LilyPond must be invoked with
-@option{-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 @rprogram{Invoking LilyPond}.
 
 @node Skipping corrected music
 @subsection Skipping corrected music

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 1aa301c710b430bd5cad207f73c88d5211dbaf1d..01784ab75ab750ac588833982d77c9d254097fe6 100644 (file)
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -464,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