(option_parser): update to 2.7.40

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

@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     M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes

@node Global issues
@chapter Global issues

This section deals with general lilypond issues, rather than
specific notation.

@menu
* Input files::                 
* A single music expression::   
* Titles and headers::          
* Paper and pages::             
* Music layout::                
* Multiple movements::          
* MIDI output::                 
@end menu


@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
* File structure (introduction)::  
* File structure::              
* Including LilyPond files::    
* Text encoding::               
@end menu


@node File structure (introduction)
@subsection File structure (introduction)

A basic example of a lilypond input file is

@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
c'4
@end example

@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.


@node File structure
@subsection File structure

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
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

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
 
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
\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.

@item
An identifier, such as
@example
foo = @{ c4 d e d @}
@end example

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

The following example shows three things that may be entered at
toplevel

@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

@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


@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 Paper and pages
@section Paper and pages

This section deals with the display of music on physical paper.

@menu
* Paper size::                  
* Page formatting::             
@end menu


@node Paper size
@subsection Paper size

@cindex paper size
@cindex page size
@cindex @code{papersize}

To change the paper size, there are two commands,
@example
#(set-default-paper-size "a4")
\paper @{
  #(set-paper-size "a4")
@}
@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{\book}, then the paper size will only
apply to that book.

Support for the following paper sizes are included by default,
@code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
@code{11x17} (also known as tabloid).

Extra sizes may be added by editing the definition for
@code{paper-alist} in the initialization file @file{scm/paper.scm}.

@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.

@example
#(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

@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
@cindex @code{first-page-number}
@item first-page-number
The value of the page number of the first page.  Default is@tie{}1.

@cindex @code{printfirst-page-number}
@item printfirst-page-number
If set to true, will print the page number in the first page.  Default is
false.

@cindex @code{print-page-number}
@item print-page-number
If set to false, page numbers will not be printed.

@cindex @code{paper-width}
@item paper-width
The width of the page.

@cindex @code{paper-height}
@item paper-height
The height of the page.

@cindex @code{top-margin}
@item top-margin
Margin between header and top of the page.

@cindex @code{bottom-margin}
@item bottom-margin
Margin between footer and bottom of the page.

@cindex @code{left-margin}
@item left-margin
Margin between the left side of the page and the beginning of the music.

@cindex @code{line-width}
@item line-width
The length of the systems.

@cindex @code{head-separation}
@item head-separation
Distance between the top-most music system and the page header.

@cindex @code{foot-separation}
@item foot-separation
Distance between the bottom-most music system and the page footer.

@cindex @code{page-top-space}
Distance from the top of the printable area to the center of the first
staff. This only works for staves which are vertically small. Big staves
are set with the top of their bounding box aligned to the top of the
printable area.

@cindex @code{ragged-bottom}
@item ragged-bottom
If set to true, systems will not be spread vertically across the page.  This
does not affect the last page.

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 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
ideal distance between the center of the bottom staff of one system
and the center of the top staff of the next system.

Increasing this will provide a more even appearance of the page at the
cost of using more vertical space.

@cindex @code{between-system-padding}
@item between-system-padding
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.

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


@cindex @code{horizontal-shift}
@item horizontal-shift
All systems (including titles and system separators) are shifted by
this amount to the right. Page markup, such as headers and footers are
not affected by this. The purpose of this variable is to make space
for instrument names at the left.

@cindex @code{after-title-space}
@item after-title-space
Amount of space between the title and the first system.

@cindex @code{after-title-space}
@item before-title-space 
Amount of space between the last system of the previous piece and the
title of the next.

@cindex @code{between-title-space}
@item between-title-space
Amount of space between consecutive titles (e.g., the title of the
book and the title of a piece).

@cindex @code{printallheaders}
@item printallheaders
Setting this to #t will print all headers for each \score in a
\book.  Normally only the piece and opus \headers are printed.

@cindex @code{systemSeparatorMarkup}
@item systemSeparatorMarkup
This contains a markup object, which will be inserted between
systems.  This is often used for orchestral scores.

The markup command @code{\slashSeparator} is provided as a sensible
default,  for example

@lilypond[ragged-right]
\book {
  \score {
    \relative { c1 \break c1 }
  }
  \paper {
    systemSeparatorMarkup = \slashSeparator
  }
}
@end lilypond


@end table
@end quotation

Example:

@example
\paper@{
  paper-width = 2\cm
  top-margin = 3\cm
  bottom-margin = 3\cm
  ragged-last-bottom = ##t
@}
@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

@example
\paper @{
  #(define bottom-margin (* 2 cm)) 
@}
@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 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.



@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
@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.

@example
\layout @{
  indent = 2.0\cm
  \context @{ \Staff
    \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
  @}
  \context @{ \Voice
    \override TextScript #'padding = #1.0
    \override Glissando #'thickness = #3
  @}
@}
@end example


@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{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.  @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)
@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 value @code{(-3 . 3)} 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)}.

The spacing of staves in a system may also be tuned per system.  This is
done with the command

@example
\overrideProperty
#"Score.NonMusicalPaperColumn"
#'line-break-system-details
#'((alignment-extra-space . 15))
@end example

@noindent
at the line break before the system to be changed. The distance
@code{15} is distributed over all staves that have a fixed distance
alignment.  For example,

@lilypond[ragged-right, fragment, relative=2, staffsize=13]
\new StaffGroup <<
  \new Staff { 
    c1\break 
        
    \overrideProperty
    #"Score.NonMusicalPaperColumn"
    #'line-break-system-details
    #'((fixed-alignment-extra-space . 15))

    c\break 
  }
  \new Staff { c c }
>>
@end lilypond

The distance for @code{alignment-extra-space} may also be negative.


To change the amount of space between systems, use
@code{between-system-space}.  A score with only one staff is still
considered to have systems, so setting @code{between-system-space} will
be much more useful than changing @code{minimum-Y-extent} of a Staff
context.

@example
\paper @{
  between-system-space = 10\mm
@}
@end example

If you simply want to tell LilyPond ``fit as much as possible onto
these pages, then expand to fill any available space on the pages,''
then use the following

@example
\paper @{
  between-system-padding = #1
  ragged-bottom=##f
  ragged-last-bottom=##f
@}
@end example


@c let's wait for a some comments before writing more.

The vertical spacing on a page can also be changed for each system individually.
Some examples are found in the example file
@inputfileref{input/regression/,page-spacing.ly}.

When setting @code{annotatespacing} in the @code{\paper} block LilyPond
will graphically indicate the dimensions of properties that may be set
for page spacing,

@lilypond[verbatim]
#(set-default-paper-size "a7" 'landscape)
\paper { annotatespacing = ##t }
{ c4 }
@end lilypond

@noindent
All units dimensions are measured in staff spaces. The pairs
(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
@var{b} the upper edge of the interval.

@seealso

Internals: Vertical alignment of staves is handled by the
@internalsref{VerticalAlignment} object. The context parameters
specifying  the vertical extent are described in connection with 
the @internalsref{Axis_group_engraver}.

Example files: @inputfileref{input/regression/,page-spacing.ly},
@inputfileref{input/regression/,alignment-vertical-spacing.ly}.




@node Vertical spacing of piano staves
@subsection Vertical spacing of piano staves

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}.

It can be adjusted as follows
@example
\new PianoStaff \with @{
  \override VerticalAlignment #'forced-distance = #7
@} @{
  ...
@}
@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 c'' <<
  \new PianoStaff \with {
    \override VerticalAlignment #'forced-distance = #7
  } <<
    \new Staff { c1 }
    \new Staff { c }
  >>
  \new PianoStaff <<
    \new Staff { c }
    \new Staff { c }
  >>
>>    
@end lilypond


It is also possible to change the distance between for each system
individually.  This is done by including the command 

@example
\overrideProperty
#"Score.NonMusicalPaperColumn"
#'line-break-system-details
#'((fixed-alignment-extra-space . 15))
@end example

@noindent
at the line break before the system to be changed. The distance
@code{15} is distributed over all staves that have a fixed distance
alignment.  For example,

@lilypond[ragged-right, fragment, relative=2, staffsize=13]
\new PianoStaff <<
  \new Staff { 
    c1\break 
        
    \overrideProperty
    #"Score.NonMusicalPaperColumn"
    #'line-break-system-details
    #'((fixed-alignment-extra-space . 15))

    c\break 
  }
  \new Staff { c c }
>>
@end lilypond

The distance for @code{fixed-alignment-extra-space} may also be
negative.

@seealso

Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.

@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,ragged-right]
{
  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|      
}
@end lilypond

Proportional notation is supported; see @ref{Proportional notation}.

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


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,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


@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
@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{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.
@c Setting indent in \paper block makes not much sense, but it works.

@c Bit verbose and vague, use examples?
The most basic settings influencing the spacing are @code{indent} and
@code{line-width}.  They are set in the @code{\layout} block.  They
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
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{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 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

@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}
>> 
@end example

@noindent
This makes the following 28 measures (assuming 4/4 time) be broken every
4 measures, and only there.

@refcommands

@code{\break}, and @code{\noBreak}.
@cindex @code{\break}
@cindex @code{\noBreak}

@seealso

Internals: @internalsref{BreakEvent}.

A linebreaking configuration can now be saved as a @code{.ly} file
automatically.  This allows vertical alignments to be stretched to
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

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.

Page breaks are computed by the @code{page-breaking} function in the
@code{\paper} block. 

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.

@example
\header@{
  breakbefore = ##t
  piece = ""
@}
@end example

@refcommands

@cindex @code{\pageBreak}
@code{\pageBreak}
@cindex @code{\noPageBreak} 
@code{\noPageBreak} 


@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 Multiple movements
@section Multiple movements

@cindex bibliographic information
@cindex titles
@cindex composer
@cindex Music engraving by LilyPond

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,

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

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

@example
\markup @{
  @var{..text..}
@}
@end example

@cindex @code{\book}

The movements and texts are combined together in a @code{\book} block,
like

@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.

@cindex Engraved by LilyPond
@cindex signature line

@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



@node MIDI output
@section MIDI output

@cindex Sound
@cindex MIDI

MIDI (Musical Instrument Digital Interface) is a standard for
connecting and controlling digital instruments.  A MIDI file is a
series of notes in a number of tracks.  It is not an actual
sound file; you need special software to translate between the
series of notes and actual sounds.

Pieces of music can be converted to MIDI files, so you can listen to
what was entered.  This is convenient for checking the music; octaves
that are off or accidentals that were mistyped stand out very much
when listening to the MIDI output.

@refbugs

Many musically interesting effects, such as swing, articulation,
slurring, etc., are not translated to midi.

The midi output allocates a channel for each staff, and one for global
settings.  Therefore the midi file should not have more than 15 staves
(or 14 if you do not use drums).  Other staves will remain silent.

Not all midi players correctly handle tempo changes in the midi
output.  Players that are known to work include
@uref{http://@/timidity@/.sourceforge@/.net/,timidity}.

@menu
* Creating MIDI files::         
* MIDI block::                  
* MIDI instrument names::       
@end menu

@node 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 
\score @{
  @var{...music...}
  \midi @{ \tempo 4=72 @}
@}
@end example 

The tempo is specified using the @code{\tempo} command.  In this
example the tempo of quarter notes is set to 72 beats per minute.


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 
\score @{
  @var{...music...}
  \midi @{ \tempo 4=72 @}
  \layout @{ @}
@}
@end example 
@cindex layout block



Ties, dynamics, and tempo changes are interpreted.  Dynamic marks,
crescendi and decrescendi translate into MIDI volume levels.  Dynamic
marks translate to a fixed fraction of the available MIDI volume
range, crescendi and decrescendi make the volume vary linearly between
their two extremes.  The fractions can be adjusted by
@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
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}, 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.

@example
\midi @{
  ...
  \context @{
    \Voice
    \remove "Dynamic_performer"
    \remove "Span_dynamic_performer"
  @}
@}
@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


The MIDI block is analogous to the layout block, but it is somewhat
simpler.  The @code{\midi} block can contain
@cindex MIDI block

@itemize @bullet
  @item a @code{\tempo} definition, and
  @item context definitions.
@end itemize

A number followed by a period is interpreted as a real number, so
for setting the tempo for dotted notes, an extra space should be
inserted, for example

@example
\midi @{ \tempo 4 . = 120 @} 
@end example


@cindex context definition

Context definitions follow precisely the same syntax as within the
\layout block.  Translation modules for sound are called performers.
The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.


@node MIDI instrument names
@subsection MIDI instrument names

@cindex instrument names
@cindex @code{Staff.midiInstrument}

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

@example
\set Staff.midiInstrument = "glockenspiel"
@var{...notes...}
@end example

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.