diff --git a/ChangeLog b/ChangeLog

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

diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index 9d2de24691400f2af39ebd6f6f444e30e96f92e1..bd2596410da33547f5b726c5a883c625376d0a66 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
@@ -168,10 +207,6 @@ A @code{\header} block.  This sets the global header block.  This
 is the block containing the definitions for book-wide settings, like
 composer, title, etc.
 
-@item
-An @code{\addquote} statement.  See @ref{Quoting other voices}
-for more information.
-
 @item
 A @code{\score} block.  This score will be collected with other
 toplevel scores, and combined as a single @code{\book}.
@@ -268,7 +303,9 @@ be entered:
 @itemize @bullet
 @item @code{\version}
 @item @code{\include}
-@item @code{\renameinput}
+@item @code{\sourcefilename}
+@item @code{\sourcefileline}
+
 @end itemize
 
 
@@ -370,6 +407,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 +416,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 +439,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
@@ -600,6 +641,15 @@ tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
 printed parts are good PR for us, so please leave the tagline if you
 can.}
 
+Headers may be completely removed by setting them to false.
+
+@example
+\header @{
+  tagline = ##f
+  composer = ##f
+@}
+@end example
+
 
 @node Custom titles
 @subsection Custom titles
@@ -667,13 +717,6 @@ composer flush right on a single line.
 @end verbatim
 
 
-@refbugs
-
-The @code{breakbefore=##t} header requires that there is a @code{piece}
-header as well.  It may be used as a normal header, or left  blank
-(@code{=""}) as in the example above, but it must be present.
-
-
 
 @node MIDI output
 @section MIDI output
@@ -720,10 +763,12 @@ to a score, for example,
 @example
 \score @{
   @var{...music...}
-  \midi @{ \tempo 4=72 @}
+  \midi @{  @}
 @}
 @end example
 
+FIXME
+
 The tempo is specified using the @code{\tempo} command.  In this
 example the tempo of quarter notes is set to 72 beats per minute.
 
@@ -735,7 +780,7 @@ be added
 @example
 \score @{
   @var{...music...}
-  \midi @{ \tempo 4=72 @}
+  \midi @{ @}
   \layout @{ @}
 @}
 @end example
@@ -801,21 +846,8 @@ will.
 
 
 The MIDI block is analogous to the layout block, but it is somewhat
-simpler.  The @code{\midi} block can contain
-@cindex MIDI block
-
-@itemize @bullet
-  @item a @code{\tempo} definition, and
-  @item context definitions.
-@end itemize
-
-A number followed by a period is interpreted as a real number, so
-for setting the tempo for dotted notes, an extra space should be
-inserted, for example
-
-@example
-\midi @{ \tempo 4 . = 120 @}
-@end example
+simpler.  The @code{\midi} block is similar to @code{\layout}. It can contain
+context definitions.
 
 
 @cindex context definition