version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.38"
+@c \version "2.11.51"
@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
@rlearning{Working on input files},
@rlearning{Music expressions explained},
-@rlearning{Score is a single (compound) music expression}.
+@rlearning{Score is a (single) compound musical expression}.
@node Multiple scores in a book
Learning Manual:
@rlearning{How LilyPond input files work}.
-@node Useful concepts and properties
-@section Useful concepts and properties
-
-
-@menu
-* Input modes::
-* Controlling 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}.
-
-@strong{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 Controlling direction and placement
-@subsection Controlling direction and placement
-
-TODO: Maybe rename section to "directions".
-
-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
-
-
@node Titles and headers
@section Titles and headers
@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
+@item a markup that will be used in place of the page number if the label
is not known;
@end enumerate
\pageBreak
\tocItem \markup "First score"
-\score {
+\score {
{
c' % ...
\tocItem \markup "Some particular point in the first score"
- d' % ...
+ d' % ...
}
}
}
}
-tocAct =
+tocAct =
#(define-music-function (parser location text) (markup?)
(add-toc-item! 'tocActMarkup text))
@end verbatim
}
}
-tocAct =
+tocAct =
#(define-music-function (parser location text) (markup?)
(add-toc-item! 'tocActMarkup text))
@section Working with input files
@menu
-* Including LilyPond files::
-* Different editions from one source::
-* Text encoding::
-* Displaying LilyPond notation::
+* Including LilyPond files::
+* Different editions from one source::
+* Text encoding::
+* Displaying LilyPond notation::
@end menu
@funindex \include
@cindex including files
-A large project may be split up into separate files. To refer to another
-file, use
+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
+The line @code{\include "otherfile.ly"} is equivalent to pasting the
+contents of @file{otherfile.ly} into the current file at the place
+where the @code{\include} appears. For example, in a large
+project you might write separate files for each instrument part
+and create a @qq{full score} file which brings together the
+individual instrument files. Normally the included file will
+define a number of variables which then become available
+for use in the full score file. Tagged sections can be
+marked in included files to assist in making them usable in
+different places in a score, see @ref{Different editions from
+one source}.
+
+Files in the current working directory may be referenced by
+specifying just the file name after the @code{\include} command.
+Files in other locations may be included by giving either a full
+path reference or a relative path reference (but use the UNIX
+forward slash, /, rather than the DOS/Windows back slash, \, as the
+directory separator.) For example, if @file{stuff.ly} is located
+one directory higher than the current working directory, use
@example
\include "../stuff.ly"
@end example
+@noindent
+or if the included orchestral parts files are all located in a
+subdirectory called @file{parts} within the current directory, use
+
+@example
+\include "parts/VI.ly"
+\include "parts/VII.ly"
+... etc
+@end example
+
+Files which are to be included can also contain @code{\include}
+statements of their own. These second-level
+@code{\include} statements are not interpreted until they have
+been brought into the main file, so the file names they specify
+must all be relative to the directory containing the main file,
+not the directory containing the included file.
+
+Files can also be included from a directory in a search path
+specified as an option when invoking LilyPond from the command
+line. The included files are then specified using just their
+file name. For example, to compile @file{main.ly} which includes
+files located in a subdirectory called @file{parts} by this method,
+cd to the directory containing @file{main.ly} and enter
+
+@example
+lilypond --include=parts main.ly
+@end example
+
+and in main.ly write
+
+@example
+\include "VI.ly"
+\include "VII.ly"
+... etc
+@end example
+
+Files which are to be included in many scores may be placed in
+the LilyPond directory @file{../ly}. (The location of this
+directory is installation-dependent - see @rlearning{Other sources
+of information}). These files can then be included simply by
+naming them on an @code{\include} statement. This is how the
+language-dependent files like @file{english.ly} are included.
+
+LilyPond includes a number of files by default when you start
+the program. These includes are not apparent to the user, but the
+files may be identified by running @code{lilypond --verbose} from
+the command line. This will display a list of paths and files that
+LilyPond uses, along with much other information. Alternatively,
+the more important of these files are discussed in @rlearning{Other
+sources of information}. These files may be edited, but changes to
+them will be lost on installing a new version of LilyPond.
+
+Some simple examples of using @code{\include} are shown in
+@rlearning{Scores and parts}.
+
+@seealso
+Learning Manual:
+@rlearning{Other sources of information},
+@rlearning{Scores and parts}.
+
+@knownissues
+
+If an included file is given a name which is the same as one in
+LilyPond's installation files, LilyPond's file from the
+installation files takes precedence.
+
+
@node Different editions from one source
@subsection Different editions from one source
-@funindex \tag
-@cindex tag
+Several mechanisms are available to facilitate the generation
+of different versions of a score from the same music source.
+Variables are perhaps most useful for combining lengthy sections
+of music and/or annotation in various ways, while tags are more
+useful for selecting one from several alternative shorter sections
+of music. Whichever method is used, separating the notation from
+the structure of the score will make it easier to change the
+structure while leaving the notation untouched.
-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.
+@menu
+* Using variables::
+* Using tags::
+@end menu
-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
+@node Using variables
+@unnumberedsubsubsec Using variables
-@example
-c1
+@cindex variables, use of
+
+If sections of the music are defined in variables they can be
+reused in different parts of the score, see @rlearning{Organizing
+pieces with variables}. For example, an @notation{a cappella}
+vocal score frequently includes a piano reduction of the parts
+for rehearsal purposes which is identical to the vocal music, so
+the music need be entered only once. Music from two variables
+may be combined on one staff, see @ref{Automatic part combining}.
+Here is an example:
+
+@lilypond[verbatim,quote]
+sopranoMusic = \relative c'' { a4 b c b8( a)}
+altoMusic = \relative g' { e4 e e f }
+tenorMusic = \relative c' { c4 b e d8( c) }
+bassMusic = \relative c' { a4 gis a d, }
+allLyrics = \lyricmode {King of glo -- ry }
<<
- \tag #'part <<
- R1 \\
- @{
- \set fontSize = #-1
- c4_"cue" f2 g4 @}
+ \new Staff = "Soprano" \sopranoMusic
+ \new Lyrics \allLyrics
+ \new Staff = "Alto" \altoMusic
+ \new Lyrics \allLyrics
+ \new Staff = "Tenor" {
+ \clef "treble_8"
+ \tenorMusic
+ }
+ \new Lyrics \allLyrics
+ \new Staff = "Bass" {
+ \clef "bass"
+ \bassMusic
+ }
+ \new Lyrics \allLyrics
+ \new PianoStaff <<
+ \new Staff = "RH" {
+ \set Staff.printPartCombineTexts = ##f
+ \partcombine
+ \sopranoMusic
+ \altoMusic
+ }
+ \new Staff = "LH" {
+ \set Staff.printPartCombineTexts = ##f
+ \clef "bass"
+ \partcombine
+ \tenorMusic
+ \bassMusic
+ }
>>
- \tag #'score R1
>>
-c1
-@end example
+@end lilypond
+
+Separate scores showing just the vocal parts or just the piano
+part can be produced by changing just the structural statements,
+leaving the musical notation unchanged.
+
+For lengthy scores, the variable definitions may be placed in
+separate files which are then included, see @ref{Including
+LilyPond files}.
+
+@node Using tags
+@unnumberedsubsubsec Using tags
+
+@funindex \tag
+@funindex \keepWithTag
+@funindex \removeWithTag
+@cindex tag
+@cindex keep tagged music
+@cindex remove tagged music
+
+The @code{\tag #'@var{partA}} command marks a music expression
+with the name @var{partA}.
+Expressions tagged in this way can be selected or filtered out by
+name later, using either @code{\keepWithTag #'@var{name}} or
+@code{\removeWithTag #'@var{name}}. The result of applying these filters
+to tagged music is as follows:
+@multitable @columnfractions .5 .5
+@headitem Filter
+ @tab Result
+@item
+Tagged music preceded by @code{\keepWithTag #'@var{name}}
+ @tab Untagged music and music tagged with @var{name} is included;
+ music tagged with any other tag name is excluded.
+@item
+Tagged music preceded by @code{\removeWithTag #'@var{name}}
+@tab Untagged music and music tagged with any tag name other than
+ @var{name} is included; music tagged with @var{name} is
+ excluded.
+@item
+Tagged music not preceded by either @code{\keepWithTag} or
+@code{\removeWithTag}
+@tab All tagged and untagged music is included.
+@end multitable
+
+The arguments of the @code{\tag}, @code{\keepWithTag} and
+@code{\removeWithTag} commands should be a symbol
+(such as @code{#'score} or @code{#'part}), followed
+by a music expression.
+
+In the following example, we see two versions of a piece of music,
+one showing trills with the usual notation, and one with trills
+explicitly expanded:
+
+@lilypond[verbatim,quote]
+music = \relative g' {
+ g8. c32 d
+ \tag #'trills {d8.\trill }
+ \tag #'expand {\repeat unfold 3 {e32 d} }
+ c32 d
+ }
+
+\score {
+ \keepWithTag #'trills \music
+}
+\score {
+ \keepWithTag #'expand \music
+}
+@end lilypond
+
+@noindent
+Alternatively, it is sometimes easier to exclude sections of music:
+
+@lilypond[verbatim,quote]
+music = \relative g' {
+ g8. c32 d
+ \tag #'trills {d8.\trill }
+ \tag #'expand {\repeat unfold 3 {e32 d} }
+ c32 d
+ }
+
+\score {
+ \removeWithTag #'expand
+ \music
+}
+\score {
+ \removeWithTag #'trills
+ \music
+}
+@end lilypond
+
+Tagged filtering can be applied to articulations, texts, etc. by
+prepending
-The same can be applied to articulations, texts, etc.: they are
-made by prepending
@example
--\tag #@var{your-tag}
+-\tag #'@var{your-tag}
@end example
-to an articulation, for example,
+
+to an articulation. For example, this would define a note with a
+conditional fingering indication and a note with a conditional
+annotation:
+
@example
-c1-\tag #'part ^4
+c1-\tag #'finger ^4
+c1-\tag #'warn ^"Watch!"
@end example
-This defines a note with a conditional fingering indication.
+Multiple tags may be placed on expressions with multiple
+@code{\tag} entries:
-@cindex keepWithTag
-@cindex removeWithTag
-By applying the @code{\keepWithTag} and @code{\removeWithTag}
-commands, tagged expressions can be filtered. For example,
-@example
+@lilypond[quote,verbatim]
+music = \relative c'' {
+ \tag #'a \tag #'both { a a a a }
+ \tag #'b \tag #'both { b b b b }
+}
<<
- @var{the music}
- \keepWithTag #'score @var{the music}
- \keepWithTag #'part @var{the music}
+\keepWithTag #'a \music
+\keepWithTag #'b \music
+\keepWithTag #'both \music
>>
-@end example
-would yield
-
-@c FIXME: broken
-@c @lilypondfile[ragged-right,quote]{tag-filter.ly}
+@end lilypond
-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,
+Multiple @code{\removeWithTag} filters may be applied to a single
+music expression to remove several differently named tagged sections:
-@example
- \tag #'original-part \tag #'transposed-part @dots{}
-@end example
+@lilypond[verbatim,quote]
+music = \relative c'' {
+\tag #'A { a a a a }
+\tag #'B { b b b b }
+\tag #'C { c c c c }
+\tag #'D { d d d d }
+}
+{
+\removeWithTag #'B
+\removeWithTag #'C
+\music
+}
+@end lilypond
+Two or more @code{\keepWithTag} filters applied to a single music
+expression will cause @emph{all} tagged sections to be removed, as
+the first filter will remove all tagged sections except the one
+named, and the second filter will remove even that tagged section.
-@knownissues
+@seealso
-Multiple rests are not merged if you create the score with both tagged
-sections.
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
+Notation Reference:
+@ref{Automatic part combining},
+@ref{Including LilyPond files}.
-@node Text encoding
-@subsection Text encoding
+@ignore
+@c This warning is more general than this placement implies.
+@c Rests are not merged whether or not they come from tagged sections.
+@c Should be deleted? -td
-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.
+@knownissues
-@c Currently not working
-@ignore
-Depending on the fonts installed, the following fragment shows Hebrew
-and Cyrillic lyrics,
+Multiple rests are not merged if you create a score with more
+than one tagged section at the same place.
-@cindex Cyrillic
-@cindex Hebrew
-@cindex ASCII, non
+@end ignore
-@li lypondfile[fontload]{utf-8.ly}
+@node Text encoding
+@subsection Text encoding
-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,
+LilyPond uses the character repertoire defined by the Unicode
+consortium and ISO/IEC 10646. This defines a unique name and
+code point for the character sets used in virtually all modern
+languages and many others too. Unicode can be implemented using
+several different encodings. LilyPond uses the UTF-8 encoding
+(UTF stands for Unicode Transformation Format) which represents
+all common Latin characters in one byte, and represents other
+characters using a variable length format of up to four bytes.
+
+The actual appearance of the characters is determined by the
+glyphs defined in the particular fonts available - a font defines
+the mapping of a subset of the Unicode code points to glyphs.
+LilyPond uses the Pango library to layout and render multi-lingual
+texts.
+
+Lilypond 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 encoded in
+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. All MS Windows systems later than NT use
+Unicode as their native character encoding, so even Notepad can
+edit and save a file in UTF-8 format. A more functional
+alternative for Windows is BabelPad.
+
+If a LilyPond input file containing a non-ASCII character is not
+saved in UTF-8 format the error message
@example
-lilypond -dbackend=texstr input/les-nereides.ly
-latex les-nereides.texstr
+FT_Get_Glyph_Name () error: invalid argument
@end example
-The last command produces @file{les-nereides.textmetrics}, which is
-read when you execute
+will be generated.
-@example
-lilypond -dbackend=tex input/les-nereides.ly
-@end example
+Here is an example showing Cyrillic, Hebrew and Portuguese
+text:
-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.
+@lilypond[verbatim,quote]
+% Cyrillic
+bulgarian = \lyricmode {
+ Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
+}
-@end ignore
+% Hebrew
+hebrew = \lyricmode {
+ זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
+}
+
+% Portuguese
+portuguese = \lyricmode {
+ à vo -- cê uma can -- ção legal
+}
-To use a Unicode escape sequence, use
+\relative {
+ c2 d e f g f e
+}
+\addlyrics { \bulgarian }
+\addlyrics { \hebrew }
+\addlyrics { \portuguese }
+@end lilypond
+
+To enter a single character for which the Unicode escape sequence
+is known but which is not available in the editor being used, enter
@example
-#(ly:export (ly:wide-char->utf-8 #x2014))
+#(ly:export (ly:wide-char->utf-8 #x03BE))
@end example
+where in this example @code{x03BE} is the hexadecimal code for the
+Unicode U+03BE character, which has the Unicode name @qq{Greek Small
+Letter Xi}. Any Unicode hexadecimal code may be substituted, and
+if all special characters are entered in this format it is not
+necessary to save the input file in UTF-8 format.
+
+@knownissues
+
+The @code{ly:export} format may be used in text within @code{\mark} or
+@code{\markup} commands but not in lyrics.
@node Displaying LilyPond notation
@subsection Displaying LilyPond notation
the results of @code{\display@{STUFF@}}, redirect the output to
a file.
+@c TODO What happens under Windows?
+
@example
lilypond file.ly >display.txt
@end example
@section Controlling output
@menu
-* Extracting fragments of notation::
-* Skipping corrected music::
+* Extracting fragments of music::
+* Skipping corrected music::
@end menu
-@node Extracting fragments of notation
-@subsection Extracting fragments of notation
+@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
(cons
(make-rhythmic-location 5 1 2)
(make-rhythmic-location 7 3 4)))
-}
+}
@end verbatim
@noindent
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.
+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
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.
+
+@c TODO Check this
+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.
+
+@menu
+* Creating MIDI files::
+* MIDI block::
+* MIDI instrument names::
+* Repeats in MIDI::
+* What else goes into the MIDI output?::
+@end menu
+
+@node Creating MIDI files
+@subsection Creating MIDI files
+
+To create a MIDI output file from a LilyPond input file, add a @code{\midi} block
+to a score, for example,
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{ @}
+@}
+@end example
+
+If there is a @code{\midi} block in a @code{\score} with no
+@code{\layout} block, only MIDI output will be produced. When
+notation is needed too, a @code{\layout} block must be also be
+present.
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{ @}
+ \layout @{ @}
+@}
+@end example
+
+Pitches, rhythms, ties, dynamics, and tempo changes are interpreted
+and translated correctly to the MIDI output. 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 effect of dynamic markings
+on the MIDI output can be removed completely, see @ref{MIDI block}.
+
+The initial tempo and later tempo changes can be specified
+with the @code{\tempo} command within the music notation. These
+are reflected in tempo changes in the MIDI output. This command
+will normally result in the metronome mark being printed, but this
+can be suppressed, see @ref{Metronome marks}. An alternative way
+of specifying the inital or overall MIDI tempo is described below,
+see @ref{MIDI block}.
+
+@ignore
+@c TODO Investigate dynamicAbsoluteVolumeFunction and the two
+@c midi..Volume properties, then document properly.
+
+The fractions can be adjusted by setting
+@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
+
+@end ignore
+
+@knownissues
+
+@c In 2.11 the following no longer seems to be a problem -td
+@ignore
+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.
+@end ignore
+
+Changes in the MIDI volume take place only on starting a note, so
+crescendi and decrescendi cannot affect the volume of a
+single note.
+
+Not all midi players correctly handle tempo changes in the midi
+output. Players that are known to work include MS Windows Media
+Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
+
+
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
+
+A @code{\midi} block must appear within a score block if MIDI output
+is required. It is analogous to the layout block, but somewhat
+simpler. Often, the @code{\midi} block is left empty, but it
+can contain context rearrangements, new context definitions or code
+to set the values of properties. For example, the following will
+set the initial tempo exported to a MIDI file without causing a tempo
+indication to be printed:
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{
+ \context @{
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 4)
+ @}
+ @}
+@}
+@end example
+
+In this example the tempo is set to 72 quarter note
+beats per minute. This kind of tempo specification cannot take
+a dotted note length as an argument. If one is required, break
+the dotted note 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
+
+@cindex MIDI context definitions
+
+Context definitions follow precisely the same syntax as those
+within a @code{\layout} block. Translation modules for sound are
+called performers. The contexts for MIDI output are defined in
+@file{ly/@/performer@/-init@/.ly} (see @rlearning{Other sources
+of information}. For example, to remove the effect of dynamics
+from the MIDI output, insert the following lines in the
+@code{\midi@{ @}} block.
+
+@example
+\midi @{
+ ...
+ \context @{
+ \Voice
+ \remove "Dynamic_performer"
+ @}
+@}
+@end example
+
+MIDI output is created only when a @code{\midi} block is included
+within a score block defined with a @code{\score} command. If it
+is placed within an explicitly instantiated score context (i.e.
+within a @code{\new Score} block) the file will fail. To solve
+this, enclose the @code{\new Score} and the @code{\midi} commands
+in a @code{\score} block.
+
+@example
+\score @{
+ \new Score @{ @dots{}notes@dots{} @}
+ \midi @{ @}
+@}
+@end example
+
+@snippets
+
+@c TODO Check header and text appear in this example
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.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 Repeats in MIDI
+@subsection Repeats in MIDI
+
+@cindex repeats in MIDI
+@funindex \unfoldRepeats
+
+With a few minor additions, all types of repeats can be represented
+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]
+\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 What else goes into the MIDI output?
+@subsection What else goes into the MIDI output?
+
+@c TODO Check grace notes - timing is suspect?
+
+@unnumberedsubsubsec Microtones
+
+@cindex microtones in MIDI
+
+Microtones consisting of half sharps and half flats are exported
+to the MIDI file and render correctly in MIDI players which support
+pitch bending. See @ref{Note names in other languages}. Here is
+an example showing all the half sharps and half flats. It can be
+copied out and compiled to test microtones in your MIDI player.
+
+@lilypond[verbatim,quote]
+\score {
+ \relative c' {
+ c cih cis cisih
+ d dih ees eeh
+ e eih f fih
+ fis fisih g gih
+ gis gisih a aih
+ bes beh b bih
+ }
+ \layout {}
+ \midi {}
+}
+@end lilypond
+
+@knownissues
+
+@c TODO List things that have no effect
+@c TODO Check these
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are not translated to midi. Also, figured bass,
+chords, and lyrics have no effect on MIDI.
+
+
+