partial update of text, fixes doc build

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

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.11.38"

@node Input syntax
@chapter Input syntax

This section deals with general LilyPond input syntax issues,
rather than specific notation.

FIXME: don't complain about anything in this chapter.  It's still
under heavy development.

@menu
* Input structure::             
* Useful concepts and properties::  
* Titles and headers::          
* Working with input files::    
* Controlling output::          
* MIDI output::                 
@end menu


@node Input structure
@section Input structure

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

@menu
* Structure of a score::        
* Multiple scores in a book::   
* File structure::              
@end menu


@node Structure of a score
@subsection Structure of a score

@funindex \score

A @code{\score} block must contain a single music expression
delimited by curly brackets:

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

@warning{There must be @strong{only one} outer music expression in
a @code{\score} block, and it @strong{must} be surrounded by
curly brackets.}

This single music expression may be of any size, and may contain
other music expressions to any complexity.  All of these examples
are music expressions:

@example
@{ c'4 c' c' c' @}
@end example

@lilypond[verbatim,quote]
{
  { c'4 c' c' c'}
  { d'4 d' d' d'}
}
@end lilypond

@lilypond[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

Comments are one exception to this general rule.  (For others see
@ref{File structure}.)  Both single-line comments and comments
delimited by @code{%@{ .. %@}} may be placed anywhere within an
input file.  They may be placed inside or outside a @code{\score}
block, and inside or outside the single music expression within a
@code{\score} block.

@seealso

Learning Manual:

@rlearning{Working on input files},
@rlearning{Music expressions explained},
@rlearning{Score is a (single) compound musical expression}.


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

@funindex \book
@cindex movements, multiple

A document may contain multiple pieces of music and text.  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

@funindex \book

All the movements and texts which appear in the same @code{.ly} file
will normally be typeset in the form of a single output file.

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

However, if you want multiple output files from the same @code{.ly}
file, then you can add multiple @code{\book} blocks, where each such
@code{\book} block will result in a separate output.  If you do not
specify any @code{\book} block in the file, LilyPond will implicitly
treat the full file as a single @code{\book} block, see @ref{File
structure}.  One important exception is within lilypond-book documents,
where you explicitly have to add a @code{\book} block, otherwise only
the first @code{\score} or @code{\markup} will appear in the output.

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.

@example
\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 File structure
@subsection File structure

@funindex \paper
@funindex \midi
@funindex \layout
@funindex \header
@funindex \score
@funindex \book

A @code{.ly} file may contain 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
book-wide settings.  If more than one such definition of
the same type is entered at the top level any definitions in the later
expressions have precedence.

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

@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{\score}s, one output file will be created
for each @code{\book} block, in which all corresponding movements
are concatenated.  The only reason to explicitly specify
@code{\book} blocks in a @code{.ly} file is if you wish to create
multiple output files from a single input file.  One exception is
within lilypond-book documents, where you explicitly have to add
a @code{\book} block if you want more than a single @code{\score}
or @code{\markup} in the same example.  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.

@cindex variables

@item
A variable, 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 variable 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 @{
  % Don't justify the output
  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
@item @code{\version}
@item @code{\include}
@item @code{\sourcefilename}
@item @code{\sourcefileline}
@item
A single-line comment, introduced by a leading @code{%} sign.

@item
A multi-line comment delimited by @code{%@{ .. %@}}.

@end itemize

@seealso

Learning Manual:
@rlearning{How LilyPond input files work}.

@node Useful concepts and properties
@section Useful concepts and properties


@menu
* Input modes::                 
* Direction and placement::     
* Distances and measurements::  
* Spanners::                    
@end menu

@node Input modes
@subsection Input modes

The way in which the notation contained within an input file is
interpreted is determined by the current input mode.

@strong{Chord mode}

This is activated with the @code{\chordmode} command, and causes
input to be interpreted with the syntax of chord notation, see
@ref{Chord notation}.  Chords are rendered as notes on a staff.

Chord mode is also activated with the @code{\chords} command.
This also creates a new @code{ChordNames} context and
causes the following input to be interpreted with the syntax of
chord notation and rendered as chord names in the @code{ChordNames}
context, see @ref{Printing chord names}.

@strong{Drum mode}

This is activated with the @code{\drummode} command, and causes
input to be interpreted with the syntax of drum notation, see
@ref{Basic percussion notation}.

Drum mode is also activated with the @code{\drums} command.
This also creates a new @code{DrumStaff} context and causes the
following input to be interpreted with the syntax of drum notation
and rendered as drum symbols on a drum staff, see @ref{Basic
percussion notation}.

@strong{Figure mode}

This is activated with the @code{\figuremode} command, and causes
input to be interpreted with the syntax of figured bass, see
@ref{Entering figured bass}.

Figure mode is also activated with the @code{\figures} command.
This also creates a new @code{FiguredBass} context and causes the
following input to be interpreted with the figured bass syntax
and rendered as figured bass symbols in the @code{FiguredBass}
context, see @ref{Introduction to figured bass}.

@strong{Fret and tab modes}

There are no special input modes for entering fret and tab symbols.

To create tab diagrams, enter notes or chords in note mode and
render them in a @code{TabStaff} context, see
@ref{Default tablatures}.

To create fret diagrams above a staff, enter them as markup
above the notes using the @code{\fret-diagram} command, see
@ref{Fret diagrams}.

@strong{Lyrics mode}

This is activated with the @code{\lyricmode} command, and causes
input to be interpreted as lyric syllables with optional durations
and associated lyric modifiers, see @ref{Vocal music}.

Lyric mode is also activated with the @code{\addlyrics} command.
This also creates a new @code{Lyrics} context and an implicit
@code{\lyricsto} command which associates the following lyrics
with the preceding music.

@strong{Markup mode}

This is activated with the @code{\markup} command, and causes
input to be interpreted with the syntax of markup, see
@ref{Text markup commands}.

@c silly work-around for texinfo broken-ness
@c (@strong{Note...} causes a spurious cross-reference in Info)
@b{Note mode}

This is the default mode or it may be activated with the
@code{\notemode} command.  Input is interpreted as pitches,
durations, markup, etc and typeset as musical notation on a staff.

It is not normally necessary to specify note mode explicitly, but
it may be useful to do so in certain situations, for example if you
are in lyric mode, chord mode or any other mode and want to insert
something that only can be done with note mode syntax.

For example, to indicate dynamic markings for the verses of a
choral pieces it is necessary to enter note mode to interpret
the markings:

@lilypond[verbatim,relative=2,quote]
{ c4 c4 c4 c4 }
\addlyrics {
  \notemode{\set stanza = \markup{ \dynamic f 1. } }
  To be sung loudly
}
\addlyrics {
  \notemode{\set stanza = \markup{ \dynamic p 2. } }
  To be sung quietly
}
@end lilypond



@node Direction and placement
@subsection Direction and placement

In typesetting music the direction and placement of many items is
a matter of choice.  For example, the stems of notes can
be directed up or down; lyrics, dynamics, and other expressive
marks may be placed above or below the staff; text may be aligned
left, right or center; etc.  Most of these choices may be left to
be determined automatically by LilyPond, but in some cases it may
be desirable to force a particular direction or placement.

@strong{Default actions}

By default some directions are always up or always down (e.g.
dynamics or fermata), while other things can alternate between
up or down based on the stem direction (like slurs or accents).

@c TODO Add table showing these

@strong{Context layout}

Contexts are positioned in a system from top to bottom in the
order in which they are encountered.  Note, however, that a
context will be created implicitly if a command is encountered
when there is no suitable context available to contain it.

@c TODO Add example ?

The default order in which contexts are laid out can be changed,
see @ref{Aligning contexts}

@strong{Articulation direction indicators}

When adding articulations to notes the direction indicator,
@code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
@code{-} (meaning @qq{use default direction}), can usually be
omitted, in which case @code{-} is assumed.  But a direction
indicator is @strong{always} required before

@itemize
@item @code{\tweak} commands
@item @code{\markup} commands
@item @code{\tag} commands
@item string markups, e.g. -"string"
@item fingering instructions, e.g. @code{-1}
@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
@end itemize

@strong{The direction property}

The position or direction of many layout objects is controlled
by the @code{direction} property.

The value of the @code{direction} property may be
set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
meaning @qq{down} or @qq{below}.  The symbols @code{UP} and
@code{DOWN} may be used instead of @code{1} and @code{-1}
respectively.  The default direction may be specified by setting
@code{direction} to @code{0} or @code{CENTER}.  Alternatively,
in many cases predefined commands
exist to specify the direction.  These are all of the form

@noindent
@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}

@noindent
where @code{xxxNeutral} means @qq{use the default direction}.
See @rlearning{Within-staff objects}.

In a few cases, arpeggio being the only common example, the value
of the @code{direction} property specifies whether the object
is to be placed to the right or left of the parent object.  In
this case @code{-1} or @code{LEFT} means @qq{to the left} and
@code{1} or @code{RIGHT} means @qq{to the right}.  @code{0}
or @code{CENTER} means @qq{use the default} direction, as before.

@ignore
These all have side-axis set to #X
AmbitusAccidental - direction has no effect
Arpeggio - works
StanzaNumber - not tried
TrillPitchAccidental - not tried
TrillPitchGroup - not tried
@end ignore



@node Distances and measurements
@subsection Distances and measurements

DISCUSS after working on other sections.

TODO: staff spaces.  Maybe move into tweaks?


@node Spanners
@subsection Spanners

Many objects of musical notation extend over several notes or even
several bars.  Examples are crescendi, trills, tuplet brackets, and
volta repeat brackets.  Such objects are called @qq{spanners}, and
have special properties to control their appearance and behaviour.
Some of these properties are common to all spanners; others are
restricted to a sub-set of the spanners.

@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::               
* Reference to page numbers::   
* Table of contents::           
@end menu


@node Creating titles
@subsection Creating titles

Titles are created for each @code{\score} block, as well as for the full
input file (or @code{\book} block).

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

@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{Formatting text}, 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

@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 @qq{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 added at the top of the entire output document.
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.  Typically, it has
the name of the movement (@code{piece} field).

@funindex oddHeaderMarkup
@item oddHeaderMarkup
  This is the page header for odd-numbered pages.

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

@funindex evenFooterMarkup
@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

@node Reference to page numbers
@subsection Reference to page numbers

A particular place of a score can be marked using the @code{\label}
command, either at top-level or inside music.  This label can then be
referred to in a markup, to get the number of the page where the marked
point is placed, using the @code{\page-ref} markup command.

@lilypond[verbatim,line-width=11.0\cm]
\header { tagline = ##f }
\book {
  \label #'firstScore
  \score {
    {
      c'1
      \pageBreak \mark A \label #'markA
      c'
    }
  }

  \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
  \markup { Mark A is on page \page-ref #'markA "0" "?" }
}
@end lilypond

The @code{\page-ref} markup command takes three arguments:
@enumerate
@item the label, a scheme symbol, eg. @code{#'firstScore};
@item a markup that will be used as a gauge to estimate the dimensions
of the markup;
@item a markup that will be used in place of the page number if the label 
is not known;
@end enumerate

The reason why a gauge is needed is that, at the time markups are
interpreted, the page breaking has not yet occurred, so the page numbers
are not yet known.  To work around this issue, the actual markup
interpretation is delayed to a later time; however, the dimensions of
the markup have to be known before, so a gauge is used to decide these
dimensions.  If the book has between 10 and 99 pages, it may be "00",
ie. a two digit number.

@predefined

@funindex \label
@code{\label}
@funindex \page-ref
@code{\page-ref}

@node Table of contents
@subsection Table of contents
A table of contents is included using the @code{\markuplines \table-of-contents}
command.  The elements which should appear in the table of contents are
entered with the @code{\tocItem} command, which may be used either at
top-level, or inside a music expression.

@verbatim
\markuplines \table-of-contents
\pageBreak

\tocItem \markup "First score"
\score { 
  {
    c'  % ...
    \tocItem \markup "Some particular point in the first score"
    d'  % ... 
  }
}

\tocItem \markup "Second score"
\score {
  {
    e' % ...
  }
}
@end verbatim

The markups which are used to format the table of contents are defined
in the @code{\paper} block.  The default ones are @code{tocTitleMarkup},
for formatting the title of the table, and @code{tocItemMarkup}, for
formatting the toc elements, composed of the element title and page
number.  These variables may be changed by the user:

@verbatim
\paper {
  %% Translate the toc title into French:
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }
  %% use larger font size
  tocItemMarkup = \markup \large \fill-line {
    \fromproperty #'toc:text \fromproperty #'toc:page
  }
}
@end verbatim

Note how the toc element text and page number are referred to in
the @code{tocItemMarkup} definition.

New commands and markups may also be defined to build more elaborated
table of contents:
@itemize
@item first, define a new markup variable in the @code{\paper} block
@item then, define a music function which aims at adding a toc element
using this markup paper variable.
@end itemize

In the following example, a new style is defined for entering act names
in the table of contents of an opera:

@verbatim
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct = 
#(define-music-function (parser location text) (markup?)
   (add-toc-item! 'tocActMarkup text))
@end verbatim

@lilypond[line-width=11.0\cm]
\header { tagline = ##f }
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct = 
#(define-music-function (parser location text) (markup?)
   (add-toc-item! 'tocActMarkup text))

\book {
  \markuplines \table-of-contents
  \tocAct \markup { Atto Primo }
  \tocItem \markup { Coro. Viva il nostro Alcide }
  \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
  \tocAct \markup { Atto Secondo }
  \tocItem \markup { Sinfonia }
  \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
  \markup \null
}
@end lilypond

@seealso

Init files: @file{ly/@/toc@/-init@/.ly}.

@predefined

@funindex \table-of-contents
@code{\table-of-contents}
@funindex \tocItem
@code{\tocItem}


@node Working with input files
@section Working with input files

@menu
* Including LilyPond files::    
* Different editions from one source::  
* Text encoding::               
* Displaying LilyPond notation::  
@end menu


@node Including LilyPond files
@subsection Including LilyPond files

@funindex \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 @q{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 @code{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 @q{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 Different editions from one source
@subsection Different editions from one source

@funindex \tag
@cindex tag

The @code{\tag} command marks music expressions with a name.  These
tagged expressions can be filtered out later.  With this mechanism it
is possible to make different versions of the same music source.

In the following example, we see two versions of a piece of music, one
for the full score, and one with cue notes for the instrumental part

@example
c1
<<
  \tag #'part <<
    R1 \\
    @{
      \set fontSize = #-1
      c4_"cue" f2 g4 @}
  >>
  \tag #'score R1
>>
c1
@end example

The same can be applied to articulations, texts, etc.: they are
made by prepending
@example
-\tag #@var{your-tag}
@end example
to an articulation, for example,
@example
c1-\tag #'part ^4
@end example

This defines a note with a conditional fingering indication.

@cindex keepWithTag
@cindex removeWithTag
By applying the @code{\keepWithTag} and @code{\removeWithTag}
commands, tagged expressions can be filtered.  For example,
@example
<<
  @var{the music}
  \keepWithTag #'score @var{the music}
  \keepWithTag #'part @var{the music}
>>
@end example
would yield

@c FIXME: broken
@c @lilypondfile[ragged-right,quote]{tag-filter.ly}

The arguments of the @code{\tag} command should be a symbol
(such as @code{#'score} or @code{#'part}), followed by a
music expression.  It is possible to put multiple tags on
a piece of music with multiple @code{\tag} entries,

@example
  \tag #'original-part \tag #'transposed-part @dots{}
@end example


@knownissues

Multiple rests are not merged if you create the score with both tagged
sections.


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

@c  Currently not working
@ignore
Depending on the fonts installed, the following fragment shows Hebrew
and Cyrillic lyrics,

@cindex Cyrillic
@cindex Hebrew
@cindex ASCII, non

@li lypondfile[fontload]{utf-8.ly}

The @TeX{} backend does not handle encoding specially at all.  Strings
in the input are put in the output as-is.  Extents of text items in the
@TeX{} backend, are determined by reading a file created via the
@file{texstr} backend,

@example
lilypond -dbackend=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 -dbackend=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.

@end ignore

To use a Unicode escape sequence, use

@example
#(ly:export (ly:wide-char->utf-8 #x2014))
@end example


@node Displaying LilyPond notation
@subsection Displaying LilyPond notation

@funindex \displayLilyMusic
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 Controlling output
@section Controlling output

@menu
* Extracting fragments of music::  
* Skipping corrected music::    
@end menu

@node Extracting fragments of music
@subsection Extracting fragments of music

It is possible to quote small fragments of a large score directly from
the output.  This can be compared to clipping a piece of a paper score
with scissors.

This is done by defining the measures that need to be cut out
separately.  For example, including the following definition


@verbatim
\layout {
  clip-regions
  = #(list
      (cons
       (make-rhythmic-location 5 1 2)
       (make-rhythmic-location 7 3 4)))
}       
@end verbatim

@noindent
will extract a fragment starting halfway the fifth measure, ending in
the seventh measure.  The meaning of @code{5 1 2} is: after a 1/2 note
in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.

More clip regions can be defined by adding more pairs of
rhythmic-locations to the list. 

In order to use this feature, LilyPond must be invoked with
@code{-dclip-systems}.  The clips are output as EPS files, and are
converted to PDF and PNG if these formats are switched on as well.

For more information on output formats, see @rprogram{Invoking lilypond}.

@node Skipping corrected music
@subsection 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.



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

@knownissues

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::       
* What goes into the MIDI?  FIXME::  
* other midi::                  
@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 @{
     \context @{
       \Score
       tempoWholesPerMinute = #(ly:make-moment 72 4)
       @}
     @}
@}
@end example

The tempo can be specified using the @code{\tempo} command within the 
actual music, see @ref{Metronome marks}.  An alternative, which does not
result in a metronome mark in the printed score, is shown in the example
above.  In this example the tempo of quarter notes is set to 72 beats per
minute. 
This kind of tempo
specification can not take dotted note lengths as an argument.  In this
case, break the dotted notes into smaller units.  For example, a tempo
of 90 dotted quarter notes per minute can be specified as 270 eighth
notes per minute

@example
tempoWholesPerMinute = #(ly:make-moment 270 8)
@end example

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 @{ @}
  \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 @rinternals{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"
  @}
@}
@end example


@knownissues

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.


MIDI output is only created when the @code{\midi} command is within
a @code{\score} block.  If you put it within an explicitly instantiated
context ( i.e. @code{\new Score} ) the file will fail.  To solve this,
enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.

@example
\score @{
  \new Score @{ @dots{}notes@dots{} @}
  \midi
@}
@end example


@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

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


@node What goes into the MIDI?  FIXME
@subsection What goes into the MIDI?  FIXME

@menu
* Repeats and MIDI::            
@end menu

@node Repeats and MIDI
@subsubsection Repeats and MIDI

@cindex expanding repeats
@funindex \unfoldRepeats

With a little bit of tweaking, all types of repeats can be present
in the MIDI output.  This is achieved by applying the
@code{\unfoldRepeats} music function.  This function changes all
repeats to unfold repeats.

@lilypond[quote,verbatim,fragment,line-width=8.0\cm]
\unfoldRepeats {
  \repeat tremolo 8 {c'32 e' }
  \repeat percent 2 { c''8 d'' }
  \repeat volta 2 {c'4 d' e' f'}
  \alternative {
    { g' a' a' g' }
    {f' e' d' c' }
  }
}
\bar "|."
@end lilypond

When creating a score file using @code{\unfoldRepeats} for MIDI,
it is necessary to make two @code{\score} blocks: one for MIDI
(with unfolded repeats) and one for notation (with volta, tremolo,
and percent repeats).  For example,

@example
\score @{
  @var{..music..}
  \layout @{ .. @}
@}
\score @{
  \unfoldRepeats @var{..music..}
  \midi @{ .. @}
@}
@end example


@node other midi
@subsection other midi

Micro tones are also exported to the MIDI file.

Figured bass has no effect on MIDI.