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 cdc6cc005d5829e0702aa4b5266ea3da7947c2c7..bd2596410da33547f5b726c5a883c625376d0a66 100644 (file)
--- a/Documentation/user/global.itely
+++ b/Documentation/user/global.itely
@@ -1,772 +1,469 @@
-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-

 @c This file is part of lilypond.tely
 
 @c This file is part of lilypond.tely
 

-@c A menu is needed before every deeper *section nesting of @node's; run 
+@c A menu is needed before every deeper *section nesting of @node's; run

 @c     M-x texinfo-all-menus-update
 @c to automatically fill in these menus before saving changes
 
 @c     M-x texinfo-all-menus-update
 @c to automatically fill in these menus before saving changes
 

-@node Output formats
-@chapter Output formats
+@node Non-musical notation
+@chapter Non-musical notation

 
 

-This is a placeholder until I can write a nice intro for this chapter.
+This section deals with general lilypond issues, rather than
+specific notation.

 
 @menu
 
 @menu

-* Paper output::                
-* Sound output::                
+* Input files::                 
+* Titles and headers::          
+* MIDI output::                 
+* Displaying LilyPond notation::  
+* Skipping corrected music::    

 @end menu
 
 
 @end menu
 
 

-@node Paper output
-@section Paper output
-
-The global paper layout is determined by three factors: the page layout, the
-line breaks, and the spacing.  These all influence each other.  The
-choice of spacing determines how densely each system of music is set.
-This influences where line breaks are chosen, and thus ultimately, how
-many pages a piece of music takes.
-
-Globally spoken, this procedure happens in three steps: first,
-flexible distances (``springs'') are chosen, based on durations.  All
-possible line breaking combinations are tried, and the one with the
-best results -- a layout that has uniform density and requires as
-little stretching or cramping as possible -- is chosen.
-
-After spacing and linebreaking, the systems are distributed across
-pages, taking into account the size of the page, and the size of the
-titles.
-
+@node Input files
+@section Input files

 
 

+The main format of input for LilyPond are text files.  By convention,
+these files end with ``@code{.ly}''.

 
 @menu
 
 @menu

-* Setting global staff size::   
-* Paper size::                  
-* Page formatting::             
-* Score layout::                
-* Vertical spacing::            
-* Vertical spacing of piano staves::  
-* Horizontal spacing::          
-* Line length::                 
-* Line breaking::               
-* Page breaking::               
-* Multiple movements::          
-* Creating titles::             
+* File structure (introduction)::  
+* Multiple scores in a book::   
+* Extracting fragments of notation::  
+* File structure::              
+* A single music expression::   
+* Including LilyPond files::    
+* Text encoding::               

 @end menu
 
 
 @end menu
 
 

-@node Setting global staff size
-@subsection Setting global staff size
-
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{layout} file
+@node File structure (introduction)
+@subsection File structure (introduction)

 
 

-To set the global staff size, use @code{set-global-staff-size}.
+A basic example of a lilypond input file is

 
 @example
 
 @example

-#(set-global-staff-size 14)
+\version "2.9.13"
+\score @{
+  @{ @}     % this is a single music expression;
+            % all the music goes in here.
+  \header @{ @}
+  \layout @{ @}
+  \midi @{ @}
+@}

 @end example
 
 @noindent
 @end example
 
 @noindent

-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
-
-The Feta font provides musical symbols at eight different
-sizes.  Each font is tuned for a different staff size: at a smaller size
-the font becomes heavier, to match the relatively heavier staff lines.
-The recommended font sizes are listed in the following table:
-
-@quotation
-@multitable @columnfractions .15 .2 .22 .2
-
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9 
-@tab pocket scores
-
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
- 
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab 
-
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab 
-
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts 
-
-@item feta23
-@tab 22.45 
-@tab 7.9
-@tab 
-
-@item feta26
-@tab 25.2 
-@tab 8.9
-@tab
-@c modern rental material?
-
-@end multitable
-@end quotation
-
-These fonts are available in any sizes.  The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@internalsref{StaffSymbol}) can be used to tune the size for individual
-staves.  The sizes of individual staves are relative to the global size.
+There are many variations of this basic pattern, but this
+example serves as a useful starting place.

 
 

+The major part of this manual is concerned with entering various
+forms of music in LilyPond.  However, many music expressions are not
+valid input on their own, for example, a @code{.ly} file containing
+only a note

 @example
 @example

-
+c'4

 @end example
 
 @end example
 

-@seealso
+@noindent
+will result in a parsing error.  Instead, music should be inside other
+expressions, which may be put in a file by themselves.  Such
+expressions are called toplevel expressions.  The next section enumerates
+them all.

 
 

-This manual: @ref{Selecting font sizes}.

 
 

+@node Multiple scores in a book
+@subsection Multiple scores in a book

 
 

-@node Paper size
-@subsection Paper size
+@funindex \book
+@cindex movements, multiple

 
 

-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
+A document may contain multiple pieces of music and texts.  Examples
+of these are an etude book, or an orchestral part with multiple
+movements.  Each movement is entered with a @code{\score} block,

 
 

-To change the paper size, there are two commands,

 @example
 @example

-#(set-default-paper-size "a4")
-\paper @{
-  #(set-paper-size "a4")
+\score @{
+  @var{..music..}

 @}
 @end example
 
 @}
 @end example
 

-The first command sets the size of all pages.  The second command sets the size
-of the pages that the @code{\paper} block applies to -- if the @code{\paper}
-block is at the top of the file, then it will apply to all pages.  If the
-@code{\paper} block is inside a @code{\score}, then the paper size will only
-apply to that score.
-
-The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
-@code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
-
-@cindex orientation
-@cindex landscape
-
-If the symbol @code{landscape} is supplied as an argument to
-@code{set-default-paper-size}, the pages will be rotated by 90 degrees,
-and wider line widths will be set correspondingly.
+and texts are entered with a @code{\markup} block,

 
 @example
 
 @example

-#(set-default-paper-size "a6" 'landscape)
-@end example 
-
-
-@node Page formatting
-@subsection Page formatting
-
-@cindex page formatting
-@cindex margins
-@cindex header, page
-@cindex footer, page
-
-LilyPond will do page layout, set margins, and add headers and
-footers to each page.
-
-The default layout responds to the following settings in the
-@code{\paper} block.
-
-@cindex @code{\paper}
-
-@quotation
-@table @code
-@item firstpagenumber
-The value of the page number of the first page.  Default is@tie{}1.
-
-@item printfirstpagenumber
-If set to true, will print the page number in the first page.  Default is
-false.
-
-@item hsize
-The width of the page.
-
-@item vsize
-The height of the page.
-
-@item topmargin
-Margin between header and top of the page.
-
-@item bottommargin
-Margin between footer and bottom of the page.
-
-@item leftmargin
-Margin between the left side of the page and the beginning of the music.
+\markup @{
+  @var{..text..}
+@}
+@end example

 
 

-@item linewidth
-The length of the systems.
+@funindex \book

 
 

-@item headsep
-Distance between the top-most music system and the page header.
+The movements and texts are combined together in a @code{\book} block,
+like

 
 

-@item footsep
-Distance between the bottom-most music system and the page footer.
+@example
+\book @{
+  \score @{
+    @var{..}
+  @}
+  \markup @{
+    @var{..}
+  @}
+  \score @{
+    @var{..}
+  @}
+@}
+@end example

 
 

-@item raggedbottom
-If set to true, systems will not be spread across the page.

 
 

-This should be set false for pieces that have only two or three
-systems per page, for example orchestral scores.
- 
-@item raggedlastbottom
-If set to false, systems will be spread to fill the last page.
+The header for each piece of music can be put inside the @code{\score}
+block.  The @code{piece} name from the header will be printed before
+each movement.  The title for the entire book can be put inside the
+@code{\book}, but if it is not present, the @code{\header} which is at
+the top of the file is inserted.

 
 

-Pieces that amply fill two pages or more should have this set to
-true.
+@example
+\book @{
+  \header @{
+    title = "Eight miniatures"
+    composer = "Igor Stravinsky"
+  @}
+  \score @{
+    @dots{}
+    \header @{ piece = "Romanze" @}
+  @}
+  \markup @{
+     ..text of second verse..
+  @}
+  \markup @{
+     ..text of third verse..
+  @}
+  \score @{
+    @dots{}
+    \header @{ piece = "Menuetto" @}
+  @}
+@}
+@end example

 
 

-@item betweensystemspace
-This dimensions determines the distance between systems.  It is the
-ideal distance between the center of the bottom staff of one system
-and the center of the top staff of the next system.
+@node Extracting fragments of notation
+@subsection Extracting fragments of notation

 
 

-Increasing this will provide a more even appearance of the page at the
-cost of using more vertical space.
+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.

 
 

-@item betweensystempadding
-This dimension is the minimum amount of white space that will always
-be present between the bottom-most symbol of one system, and the
-top-most of the next system.
+This is done by definining the measures that need to be cut out
+separately. For example, including the following definition

 
 

-Increasing this will put systems whose bounding boxes almost touch
-farther apart.

 
 

-@item aftertitlespace
-Amount of space between the title and the first system.
+@verbatim
+\layout {
+  clip-regions
+  = #(list
+      (cons
+       (make-rhythmic-location 5 1 2)
+       (make-rhythmic-location 7 3 4)))
+}       
+@end verbatim

 
 

-@item beforetitlespace 
-Amount of space between the last system of the previous piece and the
-title of the next.
+@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.

 
 

-@item betweentitlespace
-Amount of space between consecutive titles (e.g., the title of the
-book and the title of a piece).
+More clip regions can be defined by adding more pairs of
+rhythmic-locations to the list. 

 
 

-@item systemSeparatorMarkup
-This contains a markup object, which will be inserted between
-systems.  This is often used for orchestral scores.
+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.

 
 

-The markup command @code{\slashSeparator} is provided as a sensible
-default,  for example
+For more information on output formats, see @ref{Invoking lilypond}.

 
 

-@lilypond[raggedright]
-\paper {
-  systemSeparatorMarkup = \slashSeparator
-}
+@seealso

 
 

-\relative { c1 \break c1 }
-@end lilypond
+Examples: @inputfileref{input/regression/,clip-systems.ly}

 
 
 
 

-@end table
-@end quotation
+@node File structure
+@subsection File structure

 
 

-Example:
+A @code{.ly} file contains any number of toplevel expressions, where a
+toplevel expression is one of the following

 
 

+@itemize @bullet
+@item
+An output definition, such as @code{\paper}, @code{\midi}, and
+@code{\layout}.  Such a definition at the toplevel changes the default
+settings for the block entered.
+
+@item
+A direct scheme expression, such as
+@code{#(set-default-paper-size "a7" 'landscape)} or
+@code{#(ly:set-option 'point-and-click #f)}.
+
+@item
+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
+A @code{\score} block.  This score will be collected with other
+toplevel scores, and combined as a single @code{\book}.
+
+This behavior can be changed by setting the variable
+@code{toplevel-score-handler} at toplevel.  The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
+
+The @code{\score} must begin with a music expression, and may
+contain only one music expression.
+
+@item
+A @code{\book} block logically combines multiple movements
+(i.e., multiple @code{\score} blocks) in one document.  If there are
+a number of @code{\scores}, a single output file will be created
+in which all movements are concatenated.
+
+This behavior can be changed by setting the variable
+@code{toplevel-book-handler} at toplevel.  The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.
+
+@item
+A compound music expression, such as

 @example
 @example

-\paper@{
-  hsize = 2\cm
-  topmargin = 3\cm
-  bottommargin = 3\cm
-  raggedlastbottom = ##t
-@}
+@{ c'4 d' e'2 @}

 @end example
 
 @end example
 

-You can also define these values in Scheme.  In that case @code{mm},
-@code{in}, @code{pt}, and @code{cm} are variables defined in
-@file{paper-defaults.ly} with values in millimeters.  That's why the
-value has to be multiplied in the example
+This will add the piece in a @code{\score} and format it in a
+single book together with all other toplevel @code{\score}s and music
+expressions.  In other words, a file containing only the above
+music expression will be translated into

 
 @example
 
 @example

-\paper @{
-  #(define bottommargin (* 2 cm)) 
+\book @{
+  \score @{
+    \new Staff @{
+      \new Voice @{
+        @{ c'4 d' e'2 @}
+      @}
+    @}
+  @}
+       \layout @{ @}
+       \header @{ @}

 @}
 @end example
 
 @}
 @end example
 

-@cindex copyright
-@cindex tagline
-
-The default footer is empty, except for the first page, where the
-@code{copyright} field from @code{\header} is inserted, and the last
-page, where @code{tagline} from @code{\header} is added.  The default
-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.}
-
-The header and footer are created by the functions @code{make-footer}
-and @code{make-header}, defined in @code{\paper}.  The default
-implementations are in @file{scm/@/page@/-layout@/.scm}.
-
-The page layout itself is done by two functions in the
-@code{\paper} block, @code{page-music-height} and
-@code{page-make-stencil}.  The former tells the line-breaking algorithm
-how much space can be spent on a page, the latter creates the actual
-page given the system to put on it.
-
-
-@refbugs
-
-The option rightmargin is defined but doesn't set the right margin
-yet.  The value for the right margin has to be defined adjusting the
-values of the leftmargin and linewidth.
-
-The default page header puts the page number and the @code{instrument}
-field from the @code{\header} block on a line.
-
-
-@node Score layout
-@subsection Score layout
-
-@cindex @code{\layout}
-
-While @code{\paper} contains settings that relate to the page formatting
-of the whole document, @code{\layout} contains settings for score-specific
-layout.
+This behavior can be changed by setting the variable
+@code{toplevel-music-handler} at toplevel.  The default handler is
+defined in the init file @file{scm/@/lily@/.scm}.

 
 

+@item
+A markup text, a verse for example

 @example
 @example

-\layout @{
-  indent = 2.0\cm
-  \context @{ \Staff
-    minimumVerticalExtent = #'(-6 . 6
-  @}
-  \context @{ \Voice
-    \override TextScript #'padding = #1.0
-    \override Glissando #'thickness = #3
-  @}
+\markup @{
+   2.  The first line verse two.

 @}
 @end example
 
 @}
 @end example
 

+Markup texts are rendered above, between or below the scores or music
+expressions, wherever they appear.

 
 

-@seealso
-
-This manual: @ref{Changing context default settings}
-
-
-@node Vertical spacing
-@subsection Vertical spacing
-
-@cindex vertical spacing
-@cindex distance between staves
-@cindex staff distance
-@cindex between staves, distance
-@cindex staves per page
-@cindex space between staves
-
-The height of each system is determined automatically.  To prevent
-systems from bumping into each other, some minimum distances are set.
-By changing these, you can put staves closer together, and thus put
-more systems onto one page.
-
-Normally staves are stacked vertically.  To make staves maintain a
-distance, their vertical size is padded.  This is done with the
-property @code{minimumVerticalExtent}.  It takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)},
-then you could set
-
+@item
+An identifier, such as

 @example
 @example

-\set Staff.minimumVerticalExtent = #'(-3 . 3)
+foo = @{ c4 d e d @}

 @end example
 
 @end example
 

-@noindent
-This sets the vertical size of the current staff to 3 staff spaces on
-either side of the center staff line.  The argument of
-@code{minimumVerticalExtent} is interpreted as an interval, where the
-center line is the 0, so the first number is generally negative.  The
-staff can be made larger at the bottom by setting it to @code{(-6 . 4)}. 
+This can be used later on in the file by entering @code{\foo}.  The
+name of an identifier should have alphabetic characters only; no
+numbers, underscores or dashes.
+
+@end itemize

 
 

-To change the amount of space between systems, use
-@code{betweensystemspace}.  A score with only one staff is still
-considered to have systems, so setting @code{betweensystemspace}
-will be much more useful than changing @code{minimumVerticalExtent}.
+The following example shows three things that may be entered at
+toplevel

 
 @example
 \layout @{
 
 @example
 \layout @{

-  betweensystemspace = 10\mm
+  % movements are non-justified by default
+  ragged-right = ##t

 @}
 @}

-@end example
-

 
 

-@seealso
+\header @{
+   title = "Do-re-mi"
+@}

 
 

-Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
+@{ c'4 d' e2 @}
+@end example

 
 

-@refbugs

 
 

-@code{minimumVerticalExtent} is syntactic sugar for setting
-@code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
-current context.  It can only be changed score wide.
+At any point in a file, any of the following lexical instructions can
+be entered:

 
 

+@itemize @bullet
+@item @code{\version}
+@item @code{\include}
+@item @code{\sourcefilename}
+@item @code{\sourcefileline}

 
 

+@end itemize

 
 
 
 

-@node Vertical spacing of piano staves
-@subsection Vertical spacing of piano staves
+@node A single music expression
+@subsection A single music expression

 
 

-The distance between staves of a @internalsref{PianoStaff} cannot be
-computed during formatting.  Rather, to make cross-staff beaming work
-correctly, that distance has to be fixed beforehand.
- 
-The distance of staves in a @code{PianoStaff} is set with the
-@code{forced-distance} property of the
-@internalsref{VerticalAlignment} object, created in
-@internalsref{PianoStaff}.
+A @code{\score} must contain a single music expression.  However,
+this music expression may be of any size.  Recall that music
+expressions may be included inside other expressions to form
+larger expressions.  All of these examples are single music
+expressions; note the curly braces @{ @} or angle brackets <<
+>> at the beginning and ending of the music.

 
 

-It can be adjusted as follows

 @example
 @example

-\new PianoStaff \with @{
-  \override VerticalAlignment #'forced-distance = #7
-@} @{
-  ...
-@}
+@{ c'4 c' c' c' @}

 @end example
 
 @end example
 

-@noindent
-This would bring the staves together at a distance of 7 staff spaces,
-measured from the center line of each staff.
-
-The difference is demonstrated in the following example,
-@lilypond[quote,verbatim]
-\relative <<
-  \new PianoStaff \with {
-    \override VerticalAlignment #'forced-distance = #7
-  } <<
-    \new Staff { c1 }
-    \new Staff { c }
-  >>
-  \new PianoStaff <<
-    \new Staff { c }
-    \new Staff { c }
-  >>
->>    
-@end lilypond
-
-
-
-@refbugs
-
-@code{forced-distance} cannot be changed per system.
-
-
-@node Horizontal spacing
-@subsection Horizontal Spacing
-
-The spacing engine translates differences in durations into
-stretchable distances (``springs'') of differring lengths.  Longer
-durations get more space, shorter durations get less.  The shortest
-durations get a fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object). 
-The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
-
-For example, the following piece contains lots of half, quarter, and
-8th notes; the eighth note is followed by 1 note head width (NHW). 
-The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
-
-@lilypond[quote,fragment,verbatim,relative=1]
-c2 c4. c8 c4. c8 c4. c8 c8
-c8 c4 c4 c4
-@end lilypond
-
-Normally, @code{spacing-increment} is set to 1.2 staff space, which is
-approximately the width of a note head, and
-@code{shortest-duration-space} is set to 2.0, meaning that the
-shortest note gets 2.4 staff space (2.0 times the
-@code{spacing-increment}) of horizontal space.  This space is counted
-from the left edge of the symbol, so the shortest notes are generally
-followed by one NHW of space.
-
-If one would follow the above procedure exactly, then adding a single
-32nd note to a score that uses 8th and 16th notes, would widen up the
-entire score a lot.  The shortest note is no longer a 16th, but a 32nd,
-thus adding 1 NHW to every note.  To prevent this, the shortest
-duration for spacing is not the shortest note in the score, but rather
-the one which occurs most frequently.
-
-
-The most common shortest duration is determined as follows: in every
-measure, the shortest duration is determined.  The most common shortest
-duration is taken as the basis for the spacing, with the stipulation
-that this shortest duration should always be equal to or shorter than
-an 8th note.  The shortest duration is printed when you run
-@code{lilypond} with the @code{--verbose} option.
-
-These durations may also be customized.  If you set the
-@code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
-this sets the base duration for spacing.  The maximum duration for this
-base (normally an 8th), is set through @code{base-shortest-duration}.
-
-@cindex @code{common-shortest-duration}
-@cindex @code{base-shortest-duration}
-@cindex @code{stem-spacing-correction}
-@cindex @code{spacing}
-
-Notes that are even shorter than the common shortest note are
-followed by a space that is proportional to their duration relative to
-the common shortest note.  So if we were to add only a few 16th notes
-to the example above, they would be followed by half a NHW:
-
-@lilypond[quote,fragment,verbatim,relative=2]
-c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
-@end lilypond
-
-
-In the introduction (see @ref{Engraving}), it was explained that stem
-directions influence spacing.  This is controlled with the
-@code{stem-spacing-correction} property in the
-@internalsref{NoteSpacing}, object.  These are generated for every
-@internalsref{Voice} context.  The @code{StaffSpacing} object
-(generated in @internalsref{Staff} context) contains the same property
-for controlling the stem/bar line spacing.  The following example shows
-these corrections, once with default settings, and once with
-exaggerated corrections:
-
-@lilypond[quote,raggedright]
+@lilypond[ragged-right,verbatim,quote]

 {
 {

-  c'4 e''4 e'4 b'4 |
-  b'4 e''4 b'4 e''4|
-  \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
-  \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
-  c'4 e''4 e'4 b'4 |
-  b'4 e''4 b'4 e''4|      
+  { c'4 c' c' c'}
+  { d'4 d' d' d'}

 }
 @end lilypond
 
 }
 @end lilypond
 

+@lilypond[ragged-right,verbatim,quote]
+<<
+  \new Staff { c'4 c' c' c' }
+  \new Staff { d'4 d' d' d' }
+>>
+@end lilypond

 
 

-@seealso
-
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
-
-@refbugs
-
-Spacing is determined on a score wide basis.  If you have a score that
-changes its character (measured in durations) halfway during the
-score, the part containing the longer durations will be spaced too
-widely.
-
-There is no convenient mechanism to manually override spacing.  The
-following work-around may be used to insert extra space into a score.

 @example
 @example

- \once \override Score.SeparationItem #'padding = #1
+@{
+  \new GrandStaff <<
+    \new StaffGroup <<
+      \new Staff @{ \flute @}
+      \new Staff @{ \oboe @}
+    >>
+    \new StaffGroup <<
+      \new Staff @{ \violinI @}
+      \new Staff @{ \violinII @}
+    >>
+  >>
+@}

 @end example
 
 @end example
 

-No work-around exists for decreasing the amount of space.
-
-@node Line length
-@subsection Line length
-
-@cindex page breaks
-@cindex breaking pages

 
 

-@cindex @code{indent}
-@cindex @code{linewidth}
+@node Including LilyPond files
+@subsection Including LilyPond files

 
 

-@c Although linewidth can be set in \layout, it should be set in paper
-@c block, to get page layout right.
-@c Setting indent in \paper block makes not much sense, but it works.
+@funindex \include
+@cindex including files

 
 

-@c Bit verbose and vague, use examples?
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}.  They are set in the @code{\layout} block.  They
-control the indentation of the first line of music, and the lengths of
-the lines.
+A large project may be split up into separate files.  To refer to another
+file, use

 
 

-If @code{raggedright} is set to true in the @code{\layout} block, then
-the lines are justified at their natural length.  This is useful for
-short fragments, and for checking how tight the natural spacing is.
-
-@cindex page layout
-@cindex vertical spacing
-
-The option @code{raggedlast} is similar to @code{raggedright}, but
-only affects the last line of the piece.  No restrictions are put on
-that line.  The result is similar to formatting text paragraphs.  In a
-paragraph, the last line simply takes its natural length.
-@c Note that for text there are several options for the last line.
-@c While Knuth TeX uses natural length, lead typesetters use the same
-@c stretch as the previous line.  eTeX uses \lastlinefit to
-@c interpolate between both these solutions.
-
-@node Line breaking
-@subsection Line breaking
-
-@cindex line breaks
-@cindex breaking lines
-
-Line breaks are normally computed automatically.  They are chosen so
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
-
-Occasionally you might want to override the automatic breaks; you can
-do this by specifying @code{\break}.  This will force a line break at
-this point.  Line breaks can only occur at places where there are bar
-lines.  If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar
-""}.  Similarly, @code{\noBreak} forbids a line break at a 
-point.
-
-
-@cindex regular line breaks
-@cindex four bar music. 
-
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}:

 @example
 @example

-<< \repeat unfold 7 @{
-         s1 \noBreak s1 \noBreak
-         s1 \noBreak s1 \break @}
-   @emph{the real music}
->> 
+\include "otherfile.ly"

 @end example
 
 @end example
 

-@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
-
-@refcommands
+The line @code{\include "file.ly"} is equivalent to pasting the contents
+of file.ly into the current file at the place where you have the
+\include.  For example, for a large project you might write separate files
+for each instrument part and create a ``full score'' file which brings
+together the individual instrument files.
+
+The initialization of LilyPond is done in a number of files that are
+included by default when you start the program, normally transparent to the
+user.  Run lilypond --verbose to see a list of paths and files that Lily
+finds.
+
+Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
+VERSION is in the form ``2.6.1'') are on the path and available to
+@code{\include}.  Files in the
+current working directory are available to \include, but a file of the same
+name in LilyPond's installation takes precedence.  Files are
+available to \include from directories in the search path specified as an
+option when invoking @code{lilypond --include=DIR} which adds DIR to the
+search path.
+
+The @code{\include} statement can use full path information, but with the Unix
+convention @code{"/"} rather than the DOS/Windows @code{"\"}.  For example,
+if @file{stuff.ly} is located one directory higher than the current working
+directory, use

 
 

-@code{\break}, and @code{\noBreak}.
-@cindex @code{\break}
-@cindex @code{\noBreak}
+@example
+\include "../stuff.ly"
+@end example

 
 

-@seealso

 
 

-Internals: @internalsref{BreakEvent}.
+@node Text encoding
+@subsection Text encoding

 
 

+LilyPond uses the Pango library to format multi-lingual texts, and
+does not perform any input-encoding conversions.  This means that any
+text, be it title, lyric text, or musical instruction containing
+non-ASCII characters, must be utf-8.  The easiest way to enter such text is
+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.

 
 

-@node Page breaking
-@subsection Page breaking
+@c  Currently not working
+@ignore
+Depending on the fonts installed, the following fragment shows Hebrew
+and Cyrillic lyrics,

 
 

-The default page breaking may be overriden by inserting
-@code{\pageBreak} or @code{\noPageBreak} commands.  These commands are
-analogous to @code{\break} and @code{\noBreak}.  They should be
-inserted at a bar line.  These commands force and forbid a page-break
-from happening.  Of course, the @code{\pageBreak} command also forces
-a line break.
+@cindex Cyrillic
+@cindex Hebrew
+@cindex ASCII, non

 
 

-Page breaks are computed by the @code{page-breaking} function in the
-@code{\paper} block. 
+@li lypondfile[fontload]{utf-8.ly}

 
 

-To force a new page for a new piece (in a collection of pieces or a
-piece in several movements), use @code{breakbefore} in the header.
+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
+@TeX{} backend, are determined by reading a file created via the
+@file{texstr} backend,

 
 @example
 
 @example

-\header@{
-  breakbefore = ##t
-@}
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr

 @end example
 
 @end example
 

-@refcommands
-
-@cindex @code{\pageBreak}
-@code{\pageBreak}
-@cindex @code{\noPageBreak} 
-@code{\noPageBreak} 
+The last command produces @file{les-nereides.textmetrics}, which is
+read when you execute

 
 

+@example
+lilypond -b tex input/les-nereides.ly
+@end example

 
 

-@node Multiple movements
-@subsection Multiple movements
+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.

 
 

-@cindex bibliographic information
-@cindex titles
-@cindex composer
-@cindex Music engraiving by LilyPond
+@end ignore

 
 

-A document may contain multiple pieces of music and texts.  Examples
-of these are an etude book, or an orchestral part with multiple
-movements.  Each movement is entered with a @code{\score} block,
+To use a Unicode escape sequence, use

 
 @example
 
 @example

-\score @{
-  @var{..music..}
-@}
+#(ly:export (ly:wide-char->utf-8 #x2014))

 @end example
 
 @end example
 

-and texts are entered with a @code{\markup} block,

 
 

-@example
-\markup @{
-  @var{..text..}
-@}
-@end example
-
-@cindex @code{\book}
+@seealso

 
 

-The movements and texts are combined together in a @code{\book} block,
-like
+@inputfileref{input/regression,utf-8.ly}

 
 

-@example
-\book @{
-  \score @{
-    @var{..}
-  @}
-  \markup @{
-    @var{..}
-  @}
-  \score @{
-    @var{..}
-  @}
-@}
-@end example

 
 
 
 

-The header for each piece of music can be put inside the @code{\score}
-block.  The @code{piece} name from the header will be printed before
-each movement.  The title for the entire book can be put inside the
-@code{\book}, but if it is not present, the @code{\header} which is at
-the top of the file is inserted.
+@node Titles and headers
+@section Titles and headers

 
 

-@cindex Engraved by LilyPond
-@cindex signature line
+Almost all printed music includes a title and the composer's name;
+some pieces include a lot more information.

 
 

-@example 
-\book @{
-  \header @{
-    title = "Eight miniatures" 
-    composer = "Igor Stravinsky"
-  @}
-  \score @{
-    @dots{}
-    \header @{ piece = "Romanze" @}
-  @}
-  \markup @{
-     ..text of second verse..
-  @}
-  \markup @{
-     ..text of third verse..
-  @}
-  \score @{
-    @dots{}
-    \header @{ piece = "Menuetto" @}
-  @}
-@}
-@end example
+@menu
+* Creating titles::             
+* Custom titles::               
+@end menu

 
 
 @node Creating titles
 
 
 @node Creating titles


@@ -777,117 +474,219 @@ Titles are created for each @code{\score} block, and over a
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following

+
+

 @table @code
 @table @code

+@funindex dedication

 @item dedication
 The dedicatee of the music, centered at the top of the first page.
 
 @item dedication
 The dedicatee of the music, centered at the top of the first page.
 

+@funindex title

 @item title
 The title of the music, centered just below the dedication.
 
 @item title
 The title of the music, centered just below the dedication.
 

+@funindex subtitle

 @item subtitle
 Subtitle, centered below the title.
 
 @item subtitle
 Subtitle, centered below the title.
 

+@funindex subsubtitle

 @item subsubtitle
 Subsubtitle, centered below the subtitle.
 
 @item subsubtitle
 Subsubtitle, centered below the subtitle.
 

+@funindex poet

 @item poet
 Name of the poet, flush-left below the subtitle.
 
 @item poet
 Name of the poet, flush-left below the subtitle.
 

+@funindex composer

 @item composer
 Name of the composer, flush-right below the subtitle.
 
 @item composer
 Name of the composer, flush-right below the subtitle.
 

+@funindex meter

 @item meter
 Meter string, flush-left below the poet.
 
 @item meter
 Meter string, flush-left below the poet.
 

+@funindex opus

 @item opus
 Name of the opus, flush-right below the composer.
 
 @item opus
 Name of the opus, flush-right below the composer.
 

+@funindex arranger

 @item arranger
 Name of the arranger, flush-right below the opus.
 
 @item arranger
 Name of the arranger, flush-right below the opus.
 

+@funindex instrument

 @item instrument
 @item instrument

-Name of the instrument, centered below the arranger.
+Name of the instrument, centered below the arranger.  Also
+centered at the top of pages (other than the first page).

 
 

+@funindex piece

 @item piece
 Name of the piece, flush-left below the instrument.
 
 @cindex page breaks, forcing
 @item piece
 Name of the piece, flush-left below the instrument.
 
 @cindex page breaks, forcing

+@funindex breakbefore

 @item breakbefore
 @item breakbefore

-  This forces the title to start on a new page (set to ##t or ##f).
+This forces the title to start on a new page (set to ##t or ##f).
+
+@funindex copyright
+@item copyright
+Copyright notice, centered at the bottom of the first page.  To
+insert the copyright symbol, see @ref{Text encoding}.
+
+@funindex tagline
+@item tagline
+Centered at the bottom of the last page.
+

 @end table
 
 Here is a demonstration of the fields available.  Note that you
 may use any @ref{Text markup} commands in the header.
 
 @end table
 
 Here is a demonstration of the fields available.  Note that you
 may use any @ref{Text markup} commands in the header.
 

-@lilypond[quote,verbatim,linewidth=11.0\cm]
+@lilypond[quote,verbatim,line-width=11.0\cm]

 \paper {
 \paper {

-  linewidth = 9.0\cm
-  vsize = 10.0\cm
+  line-width = 9.0\cm
+  paper-height = 10.0\cm

 }
 
 \book {
   \header {
     dedication = "dedicated to me"
 }
 
 \book {
   \header {
     dedication = "dedicated to me"

-    title = \markup \center-align { "Title first line" "Title second line, longer" }
+    title = \markup \center-align { "Title first line" "Title second line,
+longer" }

     subtitle = "the subtitle,"
     subtitle = "the subtitle,"

-    subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version))
+    subsubtitle = #(string-append "subsubtitle LilyPond version "
+(lilypond-version))

     poet = "Poet"
     composer =  \markup \center-align { "composer" \small "(1847-1973)" }
     texttranslator = "Text Translator"
     poet = "Poet"
     composer =  \markup \center-align { "composer" \small "(1847-1973)" }
     texttranslator = "Text Translator"

-    meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" }
-    arranger = "Arranger"
-    opus = \markup { \fontsize #8.5 "o" \fontsize #2.5 "p" \fontsize #-2.5 "u" \fontsize #-5.3 "s" \fontsize #7.5 "       " }
+    meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
+"r" }
+    arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
+#-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }

     instrument = \markup \bold \italic "instrument"
     piece = "Piece"
   }
 
   \score {
     instrument = \markup \bold \italic "instrument"
     piece = "Piece"
   }
 
   \score {

+    { c'1 }

     \header {
       piece = "piece1"
     \header {
       piece = "piece1"

-      opus = "opus1" 
+      opus = "opus1"

     }
     }

-    { c'1 }

   }
   \markup {
       and now...
   }
   \score {
   }
   \markup {
       and now...
   }
   \score {

+    { c'1 }

     \header {
       piece = "piece2"
     \header {
       piece = "piece2"

-      opus = "opus2" 
+      opus = "opus2"

     }
     }

-    { c'1 }

   }
 }
 @end lilypond
 
   }
 }
 @end lilypond
 

+As demonstrated before, you can use multiple @code{\header} blocks.
+When same fields appear in different blocks, the latter is used.
+Here is a short example.
+
+@example
+\header @{
+  composer = "Composer"
+@}
+\header @{
+  piece = "Piece"
+@}
+\score @{
+  \new Staff @{ c'4 @}
+  \header @{
+    piece = "New piece"  % overwrite previous one
+  @}
+@}
+@end example
+
+If you define the @code{\header} inside the @code{\score} block, then
+normally only the @code{piece} and @code{opus} headers will be printed.
+Note that the music expression must come before the @code{\header}.
+
+@lilypond[quote,verbatim,line-width=11.0\cm]
+\score {
+  { c'4 }
+  \header {
+    title = "title"  % not printed
+    piece = "piece"
+    opus = "opus"
+  }
+}
+@end lilypond
+
+@funindex printallheaders
+@noindent
+You may change this behavior (and print all the headers when defining
+@code{\header} inside @code{\score}) by using
+
+@example
+\paper@{
+  printallheaders=##t
+@}
+@end example
+
+@cindex copyright
+@cindex tagline
+
+The default footer is empty, except for the first page, where the
+@code{copyright} field from @code{\header} is inserted, and the last
+page, where @code{tagline} from @code{\header} is added.  The default
+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
+

 A more advanced option is to change the definitions of the following
 variables in the @code{\paper} block.  The init file
 @file{ly/titling-init.ly} lists the default layout.
 
 @table @code
 A more advanced option is to change the definitions of the following
 variables in the @code{\paper} block.  The init file
 @file{ly/titling-init.ly} lists the default layout.
 
 @table @code

+@funindex bookTitleMarkup

 @item bookTitleMarkup
   This is the title put over an entire @code{\book} block.  Typically,
   it has the composer and the title of the piece
 @item bookTitleMarkup
   This is the title put over an entire @code{\book} block.  Typically,
   it has the composer and the title of the piece

-  
+
+@funindex scoreTitleMarkup

 @item scoreTitleMarkup
   This is the title put over a @code{\score} block within a
 @code{\book}.  Typically, it has the name of the movement (@code{piece}
 field).
 
 @item scoreTitleMarkup
   This is the title put over a @code{\score} block within a
 @code{\book}.  Typically, it has the name of the movement (@code{piece}
 field).
 

+@funindex oddHeaderMarkup

 @item oddHeaderMarkup
 @item oddHeaderMarkup

-  This is the page header for odd-numbered pages. 
+  This is the page header for odd-numbered pages.

 
 

-  @item evenHeaderMarkup
+@funindex evenHeaderMarkup
+@item evenHeaderMarkup

   This is the page header for even-numbered pages.  If unspecified,
   the odd header is used instead.
 
   By default, headers are defined such that the page number is on the
   outside edge, and the instrument is centered.
 
   This is the page header for even-numbered pages.  If unspecified,
   the odd header is used instead.
 
   By default, headers are defined such that the page number is on the
   outside edge, and the instrument is centered.
 

+@funindex oddFooterMarkup

 @item oddFooterMarkup
 @item oddFooterMarkup

-  This is the page footer for odd-numbered pages. 
-  
+  This is the page footer for odd-numbered pages.
+
+@funindex evenFotterMarkup

 @item evenFooterMarkup
   This is the page footer for even-numbered pages.  If unspecified,
   the odd header is used instead.
 @item evenFooterMarkup
   This is the page footer for even-numbered pages.  If unspecified,
   the odd header is used instead.


@@ -909,18 +708,18 @@ composer flush right on a single line.
 @verbatim
 \paper {
   bookTitleMarkup = \markup {
 @verbatim
 \paper {
   bookTitleMarkup = \markup {

-   \fill-line @{
+   \fill-line {

      \fromproperty #'header:title
      \fromproperty #'header:composer
      \fromproperty #'header:title
      \fromproperty #'header:composer

-   @}
+   }

   }
 }
 @end verbatim
 
 
 
   }
 }
 @end verbatim
 
 
 

-@node Sound output
-@section Sound output
+@node MIDI output
+@section MIDI output

 
 @cindex Sound
 @cindex MIDI
 
 @cindex Sound
 @cindex MIDI


@@ -956,17 +755,19 @@ output.  Players that are known to work include
 @end menu
 
 @node Creating MIDI files
 @end menu
 
 @node Creating MIDI files

-@subsection Creating MIDI files 
+@subsection Creating MIDI files

 
 To create a MIDI from a music piece of music, add a @code{\midi} block
 to a score, for example,
 
 
 To create a MIDI from a music piece of music, add a @code{\midi} block
 to a score, for example,
 

-@example 
+@example

 \score @{
   @var{...music...}
 \score @{
   @var{...music...}

-  \midi @{ \tempo 4=72 @}
+  \midi @{  @}

 @}
 @}

-@end example 
+@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.
 
 The tempo is specified using the @code{\tempo} command.  In this
 example the tempo of quarter notes is set to 72 beats per minute.


@@ -976,13 +777,13 @@ If there is a @code{\midi} command in a @code{\score}, only MIDI will
 be produced.  When notation is needed too, a @code{\layout} block must
 be added
 
 be produced.  When notation is needed too, a @code{\layout} block must
 be added
 

-@example 
+@example

 \score @{
   @var{...music...}
 \score @{
   @var{...music...}

-  \midi @{ \tempo 4=72 @}
+  \midi @{ @}

   \layout @{ @}
 @}
   \layout @{ @}
 @}

-@end example 
+@end example

 @cindex layout block
 
 
 @cindex layout block
 
 


@@ -996,31 +797,58 @@ their two extremes.  The fractions can be adjusted by
 For each type of MIDI instrument, a volume range can be defined.  This
 gives a basic equalizer control, which can enhance the quality of
 the MIDI output remarkably.  The equalizer can be controlled by
 For each type of MIDI instrument, a volume range can be defined.  This
 gives a basic equalizer control, which can enhance the quality of
 the MIDI output remarkably.  The equalizer can be controlled by

-setting @code{instrumentEqualizer}.
+setting @code{instrumentEqualizer}, or by setting

 
 

+@example
+\set Staff.midiMinimumVolume = #0.2
+\set Staff.midiMaximumVolume = #0.8
+@end example

 
 

-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
+To remove dynamics from the MIDI output, insert the following lines
+in the @code{\midi@{@}} section.

 
 

+@example
+\midi @{
+  ...
+  \context @{
+    \Voice
+    \remove "Dynamic_performer"
+    \remove "Span_dynamic_performer"
+  @}
+@}
+@end example

 
 

-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
+@refbugs
+
+Unterminated (de)crescendos will not render properly in the midi file,
+resulting in silent passages of music.  The workaround is to explicitly
+terminate the (de)crescendo.  For example,
+
+@example
+@{ a\< b c d\f @}
+@end example

 
 

-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
+@noindent
+will not work properly but

 
 @example
 
 @example

-\midi @{ \tempo 4 . = 120 @} 
+@{ a\< b c d\!\f @}

 @end example
 
 @end example
 

+@noindent
+will.
+
+
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
+
+
+The MIDI block is analogous to the layout block, but it is somewhat
+simpler.  The @code{\midi} block is similar to @code{\layout}. It can contain
+context definitions.
+

 
 @cindex context definition
 
 
 @cindex context definition
 


@@ -1033,7 +861,7 @@ The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
 @subsection MIDI instrument names
 
 @cindex instrument names
 @subsection MIDI instrument names
 
 @cindex instrument names

-@cindex @code{Staff.midiInstrument}
+@funindex Staff.midiInstrument

 
 The MIDI instrument name is set by the @code{Staff.midiInstrument}
 property.  The instrument name should be chosen from the list in
 
 The MIDI instrument name is set by the @code{Staff.midiInstrument}
 property.  The instrument name should be chosen from the list in


@@ -1048,3 +876,83 @@ If the selected instrument does not exactly match an instrument from
 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
 instrument is used.
 
 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
 instrument is used.
 

+
+@c  Yes, this is a cop-out; this info doesn't belong in the Scheme
+@c  chapter, but I'm not certain where to stick it.
+@c  I think I'll eventually split this chapter into a "paper/layout"
+@c  chapter and a "misc issues" chapter.  -gp
+@node Displaying LilyPond notation
+@section Displaying LilyPond notation
+
+@funindex \displayLilyMusc
+Displaying a music expression in LilyPond notation can be
+done using the music function @code{\displayLilyMusic}.  For example,
+
+@example
+@{
+  \displayLilyMusic \transpose c a, @{ c e g a bes @}
+@}
+@end example
+
+will display
+
+@example
+@{ a, cis e fis g @}
+@end example
+
+By default, LilyPond will print these messages to the console along
+with all the other messages.  To split up these messages and save
+the results of @code{\display@{STUFF@}}, redirect the output to
+a file.
+
+@example
+lilypond file.ly >display.txt
+@end example
+
+
+@node Skipping corrected music
+@section Skipping corrected music
+
+
+@funindex skipTypesetting
+@funindex showLastLength
+
+When entering or copying music, usually only the music near the end (where
+you
+are adding notes) is interesting to view and correct.  To speed up
+this correction process, it is possible to skip typesetting of all but
+the last few measures. This is achieved by putting
+
+@verbatim
+showLastLength = R1*5
+\score { ... }
+@end verbatim
+
+@noindent
+in your source file. This will render only the last 5 measures
+(assuming 4/4 time signature) of every @code{\score} in the input
+file. For longer pieces, rendering only a small part is often an order
+of magnitude quicker than rendering it completely
+
+Skipping parts of a score can be controlled in a more fine-grained
+fashion with the property @code{Score.skipTypesetting}.  When it is
+set, no typesetting is performed at all.
+
+This property is also used to control output to the MIDI file. Note that
+it skips all events, including tempo and instrument changes. You have
+been warned.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+\relative c'' {
+  c8 d
+  \set Score.skipTypesetting = ##t
+  e e e e e e e e
+  \set Score.skipTypesetting = ##f
+  c d b bes a g c2 }
+@end lilypond
+
+In polyphonic music, @code{Score.skipTypesetting} will affect all
+voices and staves, saving even more time.
+
+
+