X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fglobal.itely;h=cdd72d9e19175c02eab11ea4ac6b97030212c4d8;hb=cd97f3fa5b1275595307e89b5b070f833adb573a;hp=3b7465d30ed65183553866978585e3f47d25ade8;hpb=2fc39bfaa3434396e337919ee8c7d2f6d6f3133c;p=lilypond.git

diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index 3b7465d30e..cdd72d9e19 100644
--- a/Documentation/user/global.itely
+++ b/Documentation/user/global.itely
@@ -5,198 +5,578 @@
 @c     M-x texinfo-all-menus-update
 @c to automatically fill in these menus before saving changes
 
-@node Output formats
-@chapter Output formats
+@node Global issues
+@chapter Global issues
 
-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::                 
+* A single music expression::   
+* Titles and headers::          
+* Paper and pages::             
+* Music layout::                
+* Multiple movements::          
+* MIDI output::                 
 @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::   
-* Selecting notation font 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)::  
+* File structure::              
+* Including LilyPond files::    
+* Text encoding::               
 @end menu
 
 
-@node Setting global staff size
-@subsection Setting global staff size
+@node File structure (introduction)
+@subsection File structure (introduction)
 
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{layout} file
+A basic example of a lilypond input file is
 
-To set the global staff size, use @code{set-global-staff-size}.
+@example
+\version "2.8.0"
+\score @{
+  @{ @}     % this is a single music expression;
+            % all the music goes in here.
+  \header @{ @}
+  \layout @{ @}
+  \midi @{ @}
+@}
+@end example
 
+@noindent
+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
-#(set-global-staff-size 14)
+c'4
 @end example
 
 @noindent
-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
+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.
 
-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
+@node File structure
+@subsection File structure
 
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
+A @code{.ly} file contains any number of toplevel expressions, where a
+toplevel expression is one of the following
 
-@item feta11
-@tab 11.22
-@tab 3.9 
-@tab pocket scores
+@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
+An @code{\addquote} statement.  See @ref{Quoting other voices}
+for more information.
+
+@item
+A @code{\score} block.  This score will be collected with other
+toplevel scores, and combined as a single @code{\book}.
+
+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
+@{ c'4 d' e'2 @}
+@end example
 
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
+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
+\book @{
+  \score @{
+    \new Staff @{
+      \new Voice @{
+        @{ c'4 d' e'2 @}
+      @}
+    @}
+  @}
+	\layout @{ @}
+	\header @{ @}
+@}
+@end example
  
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab 
+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 feta16
-@tab 15.87
-@tab 5.6
-@tab 
+@item
+A markup text, a verse for example
+@example
+\markup @{
+   2.  The first line verse two.
+@}
+@end example
 
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
+Markup texts are rendered above, between or below the scores or music
+expressions, wherever they appear.
 
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts 
+@item
+An identifier, such as
+@example
+foo = @{ c4 d e d @}
+@end example
 
-@item feta23
-@tab 22.45 
-@tab 7.9
-@tab 
+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.
 
-@item feta26
-@tab 25.2 
-@tab 8.9
-@tab
-@c modern rental material?
+@end itemize
 
-@end multitable
-@end quotation
+The following example shows three things that may be entered at
+toplevel
 
-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.
+@example
+\layout @{
+  % movements are non-justified by default    
+  ragged-right = ##t
+@}
+
+\header @{
+   title = "Do-re-mi"
+@}
+   
+@{ c'4 d' e2 @}
+@end example
+
+
+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{\renameinput}
+@end itemize 
+
+
+@node Including LilyPond files
+@subsection Including LilyPond files
+
+@cindex @code{\include}
+@cindex including files
+
+A large project may be split up into separate files.  To refer to another
+file, use
 
 @example
+\include "otherfile.ly"
+@end example
 
+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
+
+@example
+\include "../stuff.ly"
 @end example
 
+
+@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.
+
+Depending on the fonts installed, the following fragment shows Hebrew
+and Cyrillic lyrics,
+
+@cindex Cyrillic
+@cindex Hebrew
+@cindex ASCII, non
+
+@lilypondfile[fontload]{utf-8.ly}
+
+The @TeX{} backend does not handle encoding specially at all.  Strings
+in the input are put in the output as-is.  Extents of text items in the
+@TeX{} backend, are determined by reading a file created via the
+@file{texstr} backend,
+
+@example
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr
+@end example
+
+The last command produces @file{les-nereides.textmetrics}, which is
+read when you execute
+
+@example
+lilypond -b tex input/les-nereides.ly
+@end example
+
+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.
+
+To use a Unicode escape sequence, use
+
+@example
+#(ly:export (ly:wide-char->utf-8 #x2014))
+@end example
+
+
 @seealso
 
-This manual: @ref{Selecting notation font size}.
+@inputfileref{input/regression,utf-8.ly}
+
+
+
+@node A single music expression
+@section A single music expression
+
+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.
+
+@example
+@{ c'4 c' c' c' @}
+@end example
+
+@lilypond[ragged-right,verbatim,quote]
+{
+  { 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
+
+@example
+@{
+  \new GrandStaff <<
+    \new StaffGroup <<
+      \new Staff @{ \flute @}
+      \new Staff @{ \oboe @}
+    >>
+    \new StaffGroup <<
+      \new Staff @{ \violinI @}
+      \new Staff @{ \violinII @}
+    >>
+  >>
+@}
+@end example
+
+
+@node Titles and headers
+@section Titles and headers
+
+Almost all printed music includes a title and the composer's name;
+some pieces include a lot more information.
+
+@menu
+* Creating titles::             
+* Custom titles::               
+@end menu
+
+
+@node Creating titles
+@subsection Creating titles
+
+Titles are created for each @code{\score} block, and over a
+@code{\book}.
+
+The contents of the titles are taken from the @code{\header} blocks.
+The header block for a book supports the following
+@table @code
+@item dedication
+The dedicatee of the music, centered at the top of the first page.
+
+@item title
+The title of the music, centered just below the dedication.
+
+@item subtitle
+Subtitle, centered below the title.
+
+@item subsubtitle
+Subsubtitle, centered below the subtitle.
+
+@item poet
+Name of the poet, flush-left below the subtitle.
+
+@item composer
+Name of the composer, flush-right below the subtitle.
+
+@item meter
+Meter string, flush-left below the poet.
+
+@item opus
+Name of the opus, flush-right below the composer.
+
+@item arranger
+Name of the arranger, flush-right below the opus.
+
+@item instrument
+Name of the instrument, centered below the arranger.  Also
+centered at the top of pages (other than the first page).
+
+@item piece
+Name of the piece, flush-left below the instrument.
+
+@cindex page breaks, forcing
+@item breakbefore
+This forces the title to start on a new page (set to ##t or ##f).
+
+@item copyright
+Copyright notice, centered at the bottom of the first page.  To
+insert the copyright symbol, see @ref{Text encoding}.
+
+@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,line-width=11.0\cm]
+\paper {
+  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" }
+    subtitle = "the subtitle,"
+    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 = \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" 
+    }
+  }
+  \markup {
+      and now...
+  }
+  \score {
+    { c'1 }
+    \header {
+      piece = "piece2"
+      opus = "opus2" 
+    }
+  }
+}
+@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
+
+@cindex @code{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
+
+
+@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
+@cindex @code{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
+  
+@cindex @code{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).
+
+@cindex @code{oddHeaderMarkup}
+@item oddHeaderMarkup
+  This is the page header for odd-numbered pages. 
+
+@cindex @code{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.
+
+@cindex @code{oddFooterMarkup}
+@item oddFooterMarkup
+  This is the page footer for odd-numbered pages. 
+  
+@cindex @code{evenFotterMarkup}
+@item evenFooterMarkup
+  This is the page footer for even-numbered pages.  If unspecified,
+  the odd header is used instead.
+
+  By default, the footer has the copyright notice on the first, and
+  the tagline on the last page.
+@end table
 
 
-@node Selecting notation font size
-@subsection Selecting notation font size
+@cindex \paper
+@cindex header
+@cindex footer
+@cindex page layout
+@cindex titles
 
-The easiest method of setting the font size of any context, is by
-setting the @code{fontSize} property.
+The following definition will put the title flush left, and the
+composer flush right on a single line.
 
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\set fontSize = #-4
-c f
-\set fontSize = #3
-g
-@end lilypond
+@verbatim
+\paper {
+  bookTitleMarkup = \markup {
+   \fill-line {
+     \fromproperty #'header:title
+     \fromproperty #'header:composer
+   }
+  }
+}
+@end verbatim
 
-@noindent
-It does not change the size of variable symbols, such as beams or
-slurs.
 
-Internally, the @code{fontSize} context property will cause the
-@code{font-size} property to be set in all layout objects.  The value
-of @code{font-size} is a number indicating the size relative to the
-standard size for the current staff height.  Each step up is an
-increase of approximately 12% of the font size.  Six steps is exactly a
-factor two.  The Scheme function @code{magstep} converts a
-@code{font-size} number to a scaling factor.
+@refbugs
 
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\override NoteHead #'font-size = #-4
-c f
-\override NoteHead #'font-size = #3
-g
-@end lilypond
+The @code{breakbefore=##t} header requires that there is a @code{piece} header as well.  It may be used as a normal header, or left  blank (@code{=""}) as in the example above, but it must be present.
 
-LilyPond has fonts in different design sizes.  The music fonts for
-smaller sizes are chubbier, while the text fonts are relatively wider.
-Font size changes are achieved by scaling the design size that is
-closest to the desired size.  The standard font size (for
-@code{font-size} equals 0), depends on the standard staff height.  For
-a 20pt staff, a 10pt font is selected.
 
-The @code{font-size} property can only be set on layout objects that
-use fonts. These are the ones supporting the
-@internalsref{font-interface} layout interface.
 
-@refcommands
+@node Paper and pages
+@section Paper and pages
 
-The following commands set @code{fontSize} for the current voice:
+This section deals with the display of music on physical paper.
 
-@cindex @code{\tiny}
-@code{\tiny}, 
-@cindex @code{\small}
-@code{\small}, 
-@cindex @code{\normalsize}
-@code{\normalsize}.
+@menu
+* Paper size::                  
+* Page formatting::             
+@end menu
 
 
 @node Paper size
@@ -238,6 +618,10 @@ and wider line widths will be set correspondingly.
 #(set-default-paper-size "a6" 'landscape)
 @end example 
 
+Setting the paper size will adjust a number of @code{\paper} variables
+(such as margins).  To use a particular paper size with altered
+@code{\paper} variables, set the paper size before setting the variables.
+
 
 @node Page formatting
 @subsection Page formatting
@@ -294,8 +678,8 @@ Margin between the left side of the page and the beginning of the music.
 @item line-width
 The length of the systems.
 
-@cindex @code{heap-separation}
-@item heap-separation
+@cindex @code{head-separation}
+@item head-separation
 Distance between the top-most music system and the page header.
 
 @cindex @code{foot-separation}
@@ -310,18 +694,24 @@ printable area.
 
 @cindex @code{ragged-bottom}
 @item ragged-bottom
-If set to true, systems will not be spread across the page.
+If set to true, systems will not be spread vertically across the page.  This
+does not affect the last page.
 
-This should be set false for pieces that have only two or three
+This should be set to true for pieces that have only two or three
 systems per page, for example orchestral scores.
  
 @cindex @code{ragged-last-bottom}
 @item ragged-last-bottom
-If set to false, systems will be spread to fill the last page.
+If set to false, systems will be spread vertically to fill the last page.
 
 Pieces that amply fill two pages or more should have this set to
 true.
 
+@cindex @code{system-count}
+@item system-count
+This variable, if set, specifies into how many lines a score should be
+broken.
+
 @cindex @code{between-system-space}
 @item between-system-space
 This dimensions determines the distance between systems.  It is the
@@ -376,11 +766,14 @@ The markup command @code{\slashSeparator} is provided as a sensible
 default,  for example
 
 @lilypond[ragged-right]
-\paper {
-  systemSeparatorMarkup = \slashSeparator
+\book {
+  \score {
+    \relative { c1 \break c1 }
+  }
+  \paper {
+    systemSeparatorMarkup = \slashSeparator
+  }
 }
-
-\relative { c1 \break c1 }
 @end lilypond
 
 
@@ -436,8 +829,189 @@ The option right-margin is defined but doesn't set the right margin
 yet.  The value for the right margin has to be defined adjusting the
 values of @code{left-margin} and @code{line-width}.
 
-The default page header puts the page number and the @code{instrument}
-field from the @code{\header} block on a line.
+The default page header puts the page number and the @code{instrument}
+field from the @code{\header} block on a line.
+
+
+
+@node Music layout
+@section Music layout
+
+This section deals with the manner in which the music is printed
+within the boundaries defined by the @code{\paper} block.
+
+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.
+
+@menu
+* Setting global staff size::   
+* Selecting notation font size::  
+* Score layout::                
+* Vertical spacing::            
+* Vertical spacing of piano staves::  
+* Horizontal spacing::          
+* Line length::                 
+* Line breaking::               
+* Page breaking::               
+@end menu
+
+
+@node Setting global staff size
+@subsection Setting global staff size
+
+@cindex font size, setting
+@cindex staff size, setting
+@cindex @code{layout} file
+
+To set the global staff size, use @code{set-global-staff-size}.
+
+@example
+#(set-global-staff-size 14)
+@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.
+
+@example
+
+@end example
+
+@seealso
+
+This manual: @ref{Selecting notation font size}.
+
+
+@node Selecting notation font size
+@subsection Selecting notation font size
+
+The easiest method of setting the font size of any context, is by
+setting the @code{fontSize} property.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\set fontSize = #-4
+c f
+\set fontSize = #3
+g
+@end lilypond
+
+@noindent
+It does not change the size of variable symbols, such as beams or
+slurs.
+
+Internally, the @code{fontSize} context property will cause the
+@code{font-size} property to be set in all layout objects.  The value
+of @code{font-size} is a number indicating the size relative to the
+standard size for the current staff height.  Each step up is an
+increase of approximately 12% of the font size.  Six steps is exactly a
+factor two.  The Scheme function @code{magstep} converts a
+@code{font-size} number to a scaling factor.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\override NoteHead #'font-size = #-4
+c f
+\override NoteHead #'font-size = #3
+g
+@end lilypond
+
+LilyPond has fonts in different design sizes.  The music fonts for
+smaller sizes are chubbier, while the text fonts are relatively wider.
+Font size changes are achieved by scaling the design size that is
+closest to the desired size.  The standard font size (for
+@code{font-size} equals 0), depends on the standard staff height.  For
+a 20pt staff, a 10pt font is selected.
+
+The @code{font-size} property can only be set on layout objects that
+use fonts. These are the ones supporting the
+@internalsref{font-interface} layout interface.
+
+@refcommands
+
+The following commands set @code{fontSize} for the current voice:
+
+@cindex @code{\tiny}
+@code{\tiny}, 
+@cindex @code{\small}
+@code{\small}, 
+@cindex @code{\normalsize}
+@code{\normalsize}.
 
 
 @node Score layout
@@ -485,11 +1059,12 @@ 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{minimum-Y-extent}.  It takes a pair of numbers, so
-if you want to make it smaller than its default @code{#'(-4 . 4)},
-then you could set. When applied to a
+property @code{minimum-Y-extent}.  When applied to a
 @internalsref{VerticalAxisGroup}, it controls the size of a horizontal
-line, such as a staff or a line of lyrics.  
+line, such as a staff or a line of lyrics.  @code{minimum-Y-extent}
+takes a pair of numbers, so
+if you want to make it smaller than its default @code{#'(-4 . 4)}
+then you could set
 
 @example
 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
@@ -762,18 +1337,27 @@ exaggerated corrections:
 
 Proportional notation is supported; see @ref{Proportional notation}.
 
-@c  check this before release  --gp
-Symbol sizes (such as accidentals) may be disregarded for determining
-horizontal spacing,
-
-@lilypond[quote,ragged-right,relative=2,fragment]
-<<
-  \time 2/4
-  \new Staff { c16[ c c c c c c c] c[ c c c c c c c] }
-  \new Staff {
-          c16[ cisis ces cis c cisis ces cis]
-    \override Score.SpacingSpanner #'uniform-stretching = ##t 
-          c16[ cisis ces cis c cisis ces cis]
+By default, spacing in tuplets depends on various non-duration
+factors (such as accidentals, clef changes, etc).  To disregard
+such symbols and force uniform equal-duration spacing, use
+@code{Score.SpacingSpanner #'uniform-stretching}.  This
+property can only be changed at the beginning of a score,
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+\new Score \with {
+  \override SpacingSpanner #'uniform-stretching = ##t
+} <<
+  \new Staff{
+    \times 4/5 {
+      c8 c8 c8 c8 c8
+    }
+    c8 c8 c8 c8
+  }
+  \new Staff{
+    c8 c8 c8 c8
+    \times 4/5 {
+      c8 c8 c8 c8 c8
+    }
   }
 >>
 @end lilypond
@@ -782,7 +1366,7 @@ horizontal spacing,
 When @code{strict-note-spacing} is set, notes are spaced without
 regard for clefs, bar lines, and grace notes,
 
-@lilypond[quote,ragged-right,relative=2,fragment]
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
 \override Score.SpacingSpanner #'strict-note-spacing = ##t 
 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c]  c32[ c32] }
 @end lilypond
@@ -819,6 +1403,7 @@ No work-around exists for decreasing the amount of space.
 @cindex @code{indent}
 @cindex @code{line-width}
 @cindex @code{ragged-right}
+@cindex @code{ragged-last}
 
 @c Although line-width can be set in \layout, it should be set in paper
 @c block, to get page layout right.
@@ -831,21 +1416,30 @@ control the indentation of the first line of music, and the lengths of
 the lines.
 
 If @code{ragged-right} is set to true in the @code{\layout} block, then
-the lines are justified at their natural length.  This is useful for
+systems ends at their natural horizontal length, instead of being spread
+horizontally to fill the whole line.  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{ragged-right}, but
+The option @code{ragged-last} is similar to @code{ragged-right}, 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.
+paragraph, the last line simply takes its natural horizontal 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.
 
+@example
+\layout @{
+  indent = #0
+  line-width = #150
+  ragged-last = ##t
+@}
+@end example
+
 
 @node Line breaking
 @subsection Line breaking
@@ -899,6 +1493,18 @@ fit pages in a second formatting run.  This is fairly new and
 complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
 for details.
 
+@refbugs
+
+Line breaks can only occur if there is a ``proper'' bar line.  A note
+which is hanging over a bar line is not proper, such as
+
+@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+c4 c2 c2 \break   % this does nothing
+c2 c4 |           % a break here would work
+c4 c2 c4 ~ \break % as does this break
+c4 c2 c4
+@end lilypond
+
 
 @node Page breaking
 @subsection Page breaking
@@ -938,7 +1544,7 @@ The @code{breakbefore=##t} header requires that there is a @code{piece} header a
 
 
 @node Multiple movements
-@subsection Multiple movements
+@section Multiple movements
 
 @cindex bibliographic information
 @cindex titles
@@ -1016,225 +1622,9 @@ the top of the file is inserted.
 @end example
 
 
-@node Creating titles
-@subsection Creating titles
-
-Titles are created for each @code{\score} block, and over a
-@code{\book}.
-
-The contents of the titles are taken from the @code{\header} blocks.
-The header block for a book supports the following
-@table @code
-@item dedication
-The dedicatee of the music, centered at the top of the first page.
-
-@item title
-The title of the music, centered just below the dedication.
-
-@item subtitle
-Subtitle, centered below the title.
-
-@item subsubtitle
-Subsubtitle, centered below the subtitle.
-
-@item poet
-Name of the poet, flush-left below the subtitle.
-
-@item composer
-Name of the composer, flush-right below the subtitle.
-
-@item meter
-Meter string, flush-left below the poet.
-
-@item opus
-Name of the opus, flush-right below the composer.
-
-@item arranger
-Name of the arranger, flush-right below the opus.
-
-@item instrument
-Name of the instrument, centered below the arranger.  Also
-centered at the top of pages (other than the first page).
-
-@item piece
-Name of the piece, flush-left below the instrument.
-
-@cindex page breaks, forcing
-@item breakbefore
-This forces the title to start on a new page (set to ##t or ##f).
-
-@item copyright
-Copyright notice, centered at the bottom of the first page.  To
-insert the copyright symbol, see @ref{Text encoding}.
-
-@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,line-width=11.0\cm]
-\paper {
-  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" }
-    subtitle = "the subtitle,"
-    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 = \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" 
-    }
-  }
-  \markup {
-      and now...
-  }
-  \score {
-    { c'1 }
-    \header {
-      piece = "piece2"
-      opus = "opus2" 
-    }
-  }
-}
-@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 @{
-  title = "Title"
-@}
-\score @{
-  \new Staff @{ c'4 @}
-  \header @{
-    title = "New title"  % 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
-
-@cindex @code{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
-
-
-@commonprop
-
-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
-@cindex @code{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
-  
-@cindex @code{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).
-
-@cindex @code{oddHeaderMarkup}
-@item oddHeaderMarkup
-  This is the page header for odd-numbered pages. 
-
-@cindex @code{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.
-
-@cindex @code{oddFooterMarkup}
-@item oddFooterMarkup
-  This is the page footer for odd-numbered pages. 
-  
-@cindex @code{evenFotterMarkup}
-@item evenFooterMarkup
-  This is the page footer for even-numbered pages.  If unspecified,
-  the odd header is used instead.
-
-  By default, the footer has the copyright notice on the first, and
-  the tagline on the last page.
-@end table
-
-
-@cindex \paper
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
-
-The following definition will put the title flush left, and the
-composer flush right on a single line.
-
-@verbatim
-\paper {
-  bookTitleMarkup = \markup {
-   \fill-line {
-     \fromproperty #'header:title
-     \fromproperty #'header:composer
-   }
-  }
-}
-@end verbatim
-
-
-@refbugs
-
-The @code{breakbefore=##t} header requires that there is a @code{piece} header as well.  It may be used as a normal header, or left  blank (@code{=""}) as in the example above, but it must be present.
-
 
-
-@node Sound output
-@section Sound output
+@node MIDI output
+@section MIDI output
 
 @cindex Sound
 @cindex MIDI
@@ -1310,7 +1700,12 @@ 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
 
 To remove dynamics from the MIDI output, insert the following lines
 in the @code{\midi@{@}} section.
@@ -1327,6 +1722,27 @@ in the @code{\midi@{@}} section.
 @end example
 
 
+@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
+
+@noindent
+will not work properly but
+
+@example
+@{ a\< b c d\!\f @}
+@end example
+
+@noindent
+will.
+
+
 @node MIDI block
 @subsection MIDI block
 @cindex MIDI block