X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fglobal.itely;h=bd2596410da33547f5b726c5a883c625376d0a66;hb=13a8e28de140702edbb0629002073972008e17ad;hp=cdc6cc005d5829e0702aa4b5266ea3da7947c2c7;hpb=9d2b0b96a7c49958f63e02812e5801a3b2b9aa55;p=lilypond.git

diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index cdc6cc005d..bd2596410d 100644
--- 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 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
 
-@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
-* Paper output::                
-* Sound output::                
+* Input files::                 
+* Titles and headers::          
+* MIDI output::                 
+* Displaying LilyPond notation::  
+* Skipping corrected music::    
 @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
-* 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
 
 
-@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
-#(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
-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
-
+c'4
 @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
-#(set-default-paper-size "a4")
-\paper @{
-  #(set-paper-size "a4")
+\score @{
+  @var{..music..}
 @}
 @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
-#(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
-\paper@{
-  hsize = 2\cm
-  topmargin = 3\cm
-  bottommargin = 3\cm
-  raggedlastbottom = ##t
-@}
+@{ c'4 d' e'2 @}
 @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
-\paper @{
-  #(define bottommargin (* 2 cm)) 
+\book @{
+  \score @{
+    \new Staff @{
+      \new Voice @{
+        @{ c'4 d' e'2 @}
+      @}
+    @}
+  @}
+	\layout @{ @}
+	\header @{ @}
 @}
 @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
-\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
 
+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
-\set Staff.minimumVerticalExtent = #'(-3 . 3)
+foo = @{ c4 d e d @}
 @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 @{
-  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
-\new PianoStaff \with @{
-  \override VerticalAlignment #'forced-distance = #7
-@} @{
-  ...
-@}
+@{ c'4 c' c' c' @}
 @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
 
+@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
- \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
 
-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
-<< \repeat unfold 7 @{
-         s1 \noBreak s1 \noBreak
-         s1 \noBreak s1 \break @}
-   @emph{the real music}
->> 
+\include "otherfile.ly"
 @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
-\header@{
-  breakbefore = ##t
-@}
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr
 @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
-\score @{
-  @var{..music..}
-@}
+#(ly:export (ly:wide-char->utf-8 #x2014))
 @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
@@ -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
+
+
 @table @code
+@funindex dedication
 @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.
 
+@funindex subtitle
 @item subtitle
 Subtitle, centered below the title.
 
+@funindex subsubtitle
 @item subsubtitle
 Subsubtitle, centered below the subtitle.
 
+@funindex poet
 @item poet
 Name of the poet, flush-left below the subtitle.
 
+@funindex composer
 @item composer
 Name of the composer, flush-right below the subtitle.
 
+@funindex meter
 @item meter
 Meter string, flush-left below the poet.
 
+@funindex opus
 @item opus
 Name of the opus, flush-right below the composer.
 
+@funindex arranger
 @item arranger
 Name of the arranger, flush-right below the opus.
 
+@funindex 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
+@funindex 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.
 
-@lilypond[quote,verbatim,linewidth=11.0\cm]
+@lilypond[quote,verbatim,line-width=11.0\cm]
 \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"
-    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,"
-    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"
-    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 {
+    { c'1 }
     \header {
       piece = "piece1"
-      opus = "opus1" 
+      opus = "opus1"
     }
-    { c'1 }
   }
   \markup {
       and now...
   }
   \score {
+    { c'1 }
     \header {
       piece = "piece2"
-      opus = "opus2" 
+      opus = "opus2"
     }
-    { c'1 }
   }
 }
 @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
+@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
-  
+
+@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).
 
+@funindex 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.
 
+@funindex 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.
@@ -909,18 +708,18 @@ composer flush right on a single line.
 @verbatim
 \paper {
   bookTitleMarkup = \markup {
-   \fill-line @{
+   \fill-line {
      \fromproperty #'header:title
      \fromproperty #'header:composer
-   @}
+   }
   }
 }
 @end verbatim
 
 
 
-@node Sound output
-@section Sound output
+@node MIDI output
+@section MIDI output
 
 @cindex Sound
 @cindex MIDI
@@ -956,17 +755,19 @@ output.  Players that are known to work include
 @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,
 
-@example 
+@example
 \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.
@@ -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
 
-@example 
+@example
 \score @{
   @var{...music...}
-  \midi @{ \tempo 4=72 @}
+  \midi @{ @}
   \layout @{ @}
 @}
-@end example 
+@end example
 @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
-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
-\midi @{ \tempo 4 . = 120 @} 
+@{ a\< b c d\!\f @}
 @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
 
@@ -1033,7 +861,7 @@ The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
 @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
@@ -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.
 
+
+@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.
+
+
+