X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Finput.itely;h=1db5b63e3d7233a287aa0adf180d2d0fbc73271a;hb=0129dea8eff59c10ba6e295f6f2cd48083fc5296;hp=fc2ead626d388a27ad52491105450a6ac0c5dfd9;hpb=40aac0ae57ee113faa860ba221d83d9e6312173e;p=lilypond.git

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index fc2ead626d..1db5b63e3d 100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -21,7 +21,7 @@ rather than specific notation.
 * Titles and headers::
 * Working with input files::
 * Controlling output::
-* MIDI output::
+* Creating MIDI output::
 * Extracting musical information::
 @end menu
 
@@ -2071,12 +2071,9 @@ LilyPond files}.
 @funindex \tag
 @funindex \keepWithTag
 @funindex \removeWithTag
-@funindex \pushToTag
-@funindex \appendToTag
 @cindex tag
 @cindex keep tagged music
 @cindex remove tagged music
-@cindex splice into tagged music
 
 The @code{\tag #'@var{partA}} command marks a music expression
 with the name @var{partA}.
@@ -2091,7 +2088,7 @@ to tagged music is as follows:
 Tagged music preceded by @code{\keepWithTag #'@var{name}} or
        @code{\keepWithTag #'(@var{name1} @var{name2}@dots{})}
 @tab Untagged music and music tagged with any of the given tag
-     names is included; 
+     names is included;
      music tagged with any other tag name is excluded.
 @item
 Tagged music preceded by @code{\removeWithTag #'@var{name}} or
@@ -2106,9 +2103,15 @@ Tagged music not preceded by either @code{\keepWithTag} or
 @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.
+@code{\removeWithTag} commands should be a symbol or list of
+symbols (such as @code{#'score} or @code{#'(violinI violinII}),
+followed by a music expression.  If @emph{and only if} the symbols
+are valid LilyPond identifiers (alphabetic characters only, no
+numbers, underscores, or dashes) which cannot be confused with notes,
+the @code{#'} may be omitted and, as a shorthand, a list of symbols
+can use the dot separator: i.e. @code{\tag #'(violinI violinII)} can
+be written @code{\tag violinI.violinII}.  The same applies to
+@code{\keepWithTag} and @code{\removeWithTag}.
 
 In the following example, we see two versions of a piece of music,
 one showing trills with the usual notation, and one with trills
@@ -2212,6 +2215,38 @@ Usually you would rather want to use a single @code{\keepWithTag}
 command with a list of multiple tags: this will only remove tagged
 sections not given in @emph{any} of the tags.
 
+@cindex tag groups
+@funindex \tagGroup
+While @code{\keepWithTag} is convenient when dealing with
+@emph{one} set of alternatives, the removal of music tagged with
+@emph{unrelated} tags is problematic when using tags for more than
+one purpose.  For that reason, @q{tag groups} of related tags can
+be declared:
+
+@example
+\tagGroup #'(violinI violinII viola cello)
+@end example
+
+declares the respective tags as belonging to one tag group.
+
+@example
+\keepWithTag #'violinI @dots{}
+@end example
+
+will then only be concerned with tags from @code{violinI}'s tag
+group: any element of the included music that is tagged with one
+or more of tags from this set but @emph{not} with @code{violinI}
+will get removed.
+
+To any @code{\keepWithTag} command, only tags from the tag groups
+of the tags given in the command are visible.
+
+Tags cannot be members of more than one tag group.
+
+@funindex \pushToTag
+@funindex \appendToTag
+@cindex splice into tagged music
+
 Sometimes you want to splice some music at a particular place in an
 existing music expression.  You can use @code{\pushToTag} and
 @code{\appendToTag} for adding material at the front or end of the
@@ -2233,9 +2268,7 @@ test = { \tag #'here { \tag #'here <<c''>> } }
 @end lilypond
 
 Both commands get a tag, the material to splice in at every occurence of
-the tag, and the tagged expression.  The commands make sure to
-copy everything that they change so that the original @code{\test}
-retains its meaning.
+the tag, and the tagged expression.
 
 @seealso
 Learning Manual:
@@ -2405,7 +2438,7 @@ lyrics and as stand-alone text below the score:
   }
   \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
 }
-\markup { "Copyright 2008--2014" \char ##x00A9 }
+\markup { "Copyright 2008--2015" \char ##x00A9 }
 @end lilypond
 
 @cindex copyright sign
@@ -2481,40 +2514,54 @@ Installed Files:
 * Replacing the notation font::
 @end menu
 
+@funindex clip-regions
+@cindex Fragments, music
+@cindex Music fragments
+
 @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
-
+It is possible to output one or more fragments of a score by defining
+the explicit location of the music to be extracted within the
+@code{\layout} block of the the input file using the @code{clip-regions}
+function, and then running LilyPond with the @option{-dclip-systems}
+option;
 
-@verbatim
-\layout {
+@example
+\layout @{
   clip-regions
   = #(list
       (cons
        (make-rhythmic-location 5 1 2)
        (make-rhythmic-location 7 3 4)))
-}
-@end verbatim
+@}
+@end example
 
 @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.
+This example will extract a single fragment of the input file
+@emph{starting} after a half-note duration in fifth measure
+(@code{5 1 2}) and @emph{ending} after the third quarter-note in the
+seventh measure (@code{7 3 4}).
+
+Additional fragments can be extracted by adding more pairs of
+@code{make-rhythmic-location} entries to the @code{clip-regions} list in
+the @code{\layout} block.
+
+By default, each music fragment will be output as a separate @code{EPS}
+file, but other formats such as @code{PDF} or @code{PNG} can also be
+created if required.  The extracted music is output as if had been
+literally @q{cut} from the original printed score so if a fragment runs
+over one or more lines, a separate ouput file for each line will be
+generated.
+
+@seealso
+Notation Reference:
+@ref{The layout block}.
 
-More clip regions can be defined by adding more pairs of
-rhythmic-locations to the list.
+Application Usage
+@rprogram{Command-line usage}.
 
-In order to use this feature, LilyPond must be invoked with
-@option{-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
@@ -2618,424 +2665,212 @@ information on these and other specifics, including licensing of
 Gonville.
 
 
-@node MIDI output
-@section MIDI output
+@node Creating MIDI output
+@section Creating 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.
+LilyPond can produce files that conform to the MIDI (Musical Instrument
+Digital Interface) standard and so allow for the checking of the music
+output aurally (with the help of an application or device that
+understands MIDI).  Listening to MIDI output may also help in spotting
+errors such as notes that have been entered incorrectly or are missing
+accidentals and so on.
 
-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.
-
-Standard MIDI output is somewhat crude; optionally, an enhanced and
-more realistic MIDI output is available by means of
-@ref{The Articulate script}.
-
-The MIDI output allocates a channel for each staff, and reserves channel
-10 for drums.  There are only 16 MIDI channels per device, so if the
-score contains more than 15 staves, MIDI channels will be reused.
+MIDI files do not contain sound (like AAC, MP3 or Vorbis files) but
+require additional software to produce sound from them.
 
 @menu
-* Creating MIDI files::
-* MIDI Instruments::
-* What goes into the MIDI output?::
-* Repeats in MIDI::
+* Supported notation for MIDI::
+* Unsupported notation for MIDI::
+* The MIDI block::
 * Controlling MIDI dynamics::
-* Percussion in MIDI::
-* The Articulate script::
+* Using MIDI instruments::
+* Using repeats with MIDI::
+* Enhancing MIDI output::
 @end menu
 
-@node Creating MIDI files
-@subsection Creating MIDI files
-
-@cindex MIDI block
-To create a MIDI output file from a LilyPond file, insert a @code{\midi}
-block inside a @code{\score} block;
-
-@example
-\score @{
-  @var{@dots{}music@dots{}}
-  \layout @{ @}
-  \midi @{ @}
-@}
-@end example
-
-If there is @emph{only} a @code{\midi} block in a @code{\score} (i.e.
-without any @code{\layout} block), then @emph{only} MIDI output will be
-produced.  No musical notation will be typeset.
-
-@example
-\score @{
-  @var{@dots{}music@dots{}}
-  \midi @{ @}
-@}
-@end example
-
-Dynamics, pitches, rhythms, tempo changes and ties are all interpreted
-and translated correctly.  Dynamic @q{marks} translate into volume
-levels with a @q{fixed fraction} of the available MIDI volume range;
-crescendi and decrescendi make the volume vary linearly between their
-two extremes.
-
-All @code{\tempo} indications, including all subsequent tempo changes,
-specified within the music notation will be reflected in the MIDI
-output.
-
-Usually it is enough to leave the @code{\midi} block empty, but it can
-contain context rearrangements, new context definitions or code to set
-the values of properties.  Here the tempo is set to 72 quarter-note
-beats per minute, but @emph{only} for the MIDI's audio playback.
-
-@example
-\score @{
-  @var{@dots{}music@dots{}}
-  \midi @{
-    \tempo 4 = 72
-  @}
-@}
-@end example
-
-Note that @code{\tempo} is actually a command for setting properties
-during the interpretation of the music and in the context of output
-definitions, like a @code{\midi} block, is reinterpreted as if it were a
-context modification.
-
-@cindex MIDI context definitions
-
-Context definitions follow the same syntax as those in a @code{\layout}
-block;
-
-@example
-\score @{
-  @var{@dots{}music@dots{}}
-  \midi @{
-    \context @{
-      \Voice
-      \remove "Dynamic_performer"
-    @}
-  @}
-@}
-@end example
-
-removes the effect of dynamics from the MIDI output.  Translation
-modules for sound are called @q{performers}.
-
-@snippets
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
-
-@seealso
-Learning Manual:
-@rlearning{Other sources of information}.
-
-Notation Reference:
-@ref{Expressive marks},
-@ref{Score layout}.
-
-Installed Files:
-@file{ly/performer-init.ly}.
-
-Snippets:
-@rlsr{MIDI}.
-
-Internals Reference:
-@rinternals{Dynamic_performer}.
-
-@knownissues
-Some operating systems require a @emph{specific} file extension for MIDI
-files.  If a different extension is preferred insert the following line
-at the top-level of the input file, before the start of any
-@code{\book}, @code{\bookpart} or @code{\score} blocks;
-
-@example
-#(ly:set-option 'midi-extension "mid")
-@end example
-
-This will set the default extension for MIDI files to @code{.mid}.
-
-Alternatively, an option can be supplied on the command line:
-
-@example
-lilypond -dmidi-extension=mid MyFile.ly
-@end example
+@cindex MIDI, Supported notation
 
-Changes in the MIDI volume take place only on starting a note, so
-crescendi and decrescendi cannot affect the volume of a single note.
-
-Some MIDI players may not always correctly handle tempo changes in the
-midi output.
+@node Supported notation for MIDI
+@subsection Supported notation for MIDI
 
-Changes to @code{midiInstrument} (and other MIDI options) at the
-beginning of a staff may appear twice in the MIDI output.
-
-
-@node MIDI Instruments
-@subsection MIDI Instruments
-
-@cindex instrument names
-@cindex MIDI, instruments
-@funindex Staff.midiInstrument
-
-The MIDI instrument to be used is specified by setting the
-@code{Staff.midiInstrument} property to the instrument name.  The name
-should be chosen from the list in @ref{MIDI instruments}.
-
-@example
-\new Staff @{
-  \set Staff.midiInstrument = #"glockenspiel"
-  @var{@dots{}notes@dots{}}
-@}
-@end example
-
-@example
-\new Staff \with @{midiInstrument = #"cello"@} @{
-  @var{@dots{}notes@dots{}}
-@}
-@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.
-
-@seealso
-Notation Reference:
-@ref{MIDI instruments}.
-
-Internals Reference:
-@rinternals{Dynamic_performer}.
-
-
-@node What goes into the MIDI output?
-@subsection What goes into the MIDI output?
-
-@c TODO Check grace notes - timing is suspect?
-
-@menu
-* Supported in MIDI::
-* Unsupported in MIDI::
-@end menu
-
-@node Supported in MIDI
-@unnumberedsubsubsec Supported in MIDI
-
-@cindex Pitches in MIDI
-@cindex MIDI, Pitches
-@cindex Quarter tones in MIDI
-@cindex MIDI, quarter tones
-@cindex Microtones in MIDI
-@cindex MIDI, microtones
-@cindex Chord names in MIDI
-@cindex MIDI, chord names
-@cindex Rhythms in MIDI
-@cindex MIDI, Rhythms
-@cindex Articlulate scripts
-@cindex MIDI, articulations
-@cindex articulations in MIDI
-@cindex trills in MIDI
-@cindex turns in MIDI
-@cindex rallentando in MIDI
-@cindex accelerando in MIDI
-@c TODO etc
-
-The following items of notation are reflected in the MIDI output:
+The following musical notation can be used with LilyPond's default
+capabilities to produce MIDI output;
 
 @itemize
-@item Pitches
-@item Microtones (See @ref{Accidentals}.  Rendering needs a
-player that supports pitch bend.)
+@item Breath marks
 @item Chords entered as chord names
+@item Crescendi, decrescendi over multiple notes.  The volume is altered
+linearly between the two extremes
+@item Dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf}
+@item Microtones but @emph{not} microtonal chords.  A MIDI player that
+supports pitch bending will also be required.
+@item Lyrics
+@item Pitches
 @item Rhythms entered as note durations, including tuplets
-@item Tremolos entered without @q{@code{:}[@var{number}]}
+@item @q{Simple} articulations; staccato, staccatissimo, accent, marcato
+and portato
+@item Tempo changes using the @code{\tempo} function
 @item Ties
-@item Dynamic marks
-@item Crescendi, decrescendi over multiple notes
-@item Tempo changes entered with a tempo marking
-@item Lyrics
-@item Simple articulations: staccato, staccatissimo, accent, marcato, portato
-@item @ref{Breath marks}
+@item Tremolos that are @emph{not} entered with a
+@q{@code{:}[@var{number}]} value
 @end itemize
 
-There is a script that adds the following items; see
-@ref{The Articulate script}:
+When combined with the @file{articulate} script the following,
+additional musical notation can be output to MIDI;
 
 @itemize
-@item Slurs and phrasing slurs
-@item Ornaments (mordents, trills, turns, etc.)
-@item Rallentando, accelerando, ritard, and a tempo
-@end itemize
+@item Appogiaturas.  These are made to take half the value of the note
+following (without taking dots into account).  For example;
 
-@seealso
-Notation Reference:
-@ref{Accidentals},
-@ref{Breath marks},
-@ref{Expressive marks}.
+@example
+\appoggiatura c8 d2.
+@end example
 
-Installed Files:
-@file{ly/articulate.ly}.
+@noindent
+The c will take the value of a crotchet.
 
+@item Ornaments (i.e. mordents, trills and turns et al.)
+@item Rallentando, accelerando, ritardando and a tempo
+@item Slurs, including phrasing slurs
+@item Tenuto
+@end itemize
 
-@node Unsupported in MIDI
-@unnumberedsubsubsec Unsupported in MIDI
+@noindent
+See @ref{Enhancing MIDI output}.
 
-@c TODO index as above
+@cindex MIDI, Unsupported notation
 
-The following items of notation have no effect on the MIDI output, even
-if you use @ref{The Articulate script}:
+@node Unsupported notation for MIDI
+@subsection Unsupported notation for MIDI
+
+The following items of musical notation cannot be output to MIDI;
 
 @itemize
-@item Rhythms entered as annotations, e.g. swing
-@item Tempo changes entered as annotations with no tempo marking
-@item Fermatas
-@item Other articulations
-@item Crescendi, decrescendi over a single note
-@item Tremolos entered with @q{@code{:}[@var{number}]}
+@item Articulations other than staccato, staccatissimo, accent, marcato
+and portato
+@item Crescendi and decrescendi over a @emph{single} note
+@item Fermata
 @item Figured bass
+@item Glissandi
+@item Falls and doits
 @item Microtonal chords
-@item Glissandi, falls and doits
+@item Rhythms entered as annotations, e.g. swing
+@item Tempo changes without @code{\tempo} (e.g. entered as annotations)
+@item Tremolos that @emph{are} entered with a @q{@code{:}[@var{number}]}
+value
 @end itemize
 
-@seealso
-Installed Files:
-@file{ly/articulate.ly}.
 
+@node The MIDI block
+@subsection The MIDI block
 
-@node Repeats in MIDI
-@subsection Repeats in MIDI
+@cindex MIDI block
 
-@cindex repeats in MIDI
-@funindex \unfoldRepeats
+To create a MIDI output file from a LilyPond input file, insert a
+@code{\midi} block, which can be empty, within the @code{\score} block;
 
-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.
+@example
+\score @{
+  @var{@dots{} music @dots{}}
+  \layout @{ @}
+  \midi @{ @}
+@}
+@end example
 
-@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
+@warning{ A @code{\score} block that, as well as the music, contains
+only a @code{\midi} block (i.e. @emph{without} the @code{\layout}
+block), will only produce MIDI output files.  No notation will be
+printed.}
 
-In scores containing multiple voices, unfolding of repeats in MIDI
-output will only occur correctly if @emph{each} voice contains fully
-notated repeat indications.
+The default output file extension (@code{.midi}) can be changed by using
+the @code{-dmidi-extension} option with the @code{lilypond} command:
 
-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):
+@example
+lilypond -dmidi-extension=mid MyFile.ly
+@end example
+
+Alternatively, add the following Scheme expression before the start of
+either the @code{\book}, @code{\bookpart} or @code{\score} blocks.  See
+@ref{File structure}.
 
 @example
-\score @{
-  @var{@dots{}music@dots{}}
-  \layout @{ @dots{} @}
-@}
-\score @{
-  \unfoldRepeats @var{@dots{}music@dots{}}
-  \midi @{ @dots{} @}
-@}
+#(ly:set-option 'midi-extension "mid")
 @end example
 
 @seealso
 Notation Reference:
-@ref{Score layout}.
+@ref{File structure}.
 
 Installed Files:
-@file{ly/articulate.ly}.
+@file{scm/midi.scm}.
+
+@knownissues
+There are fifteen MIDI channels available and one additional channel
+(#10) for drums.  Staves are assigned to channels in sequence, so a
+score that contains more than fifteen staves will result in the extra
+staves sharing (but not overwriting) the same MIDI channel.  This may be
+a problem if the sharing staves have conflicting, channel-based, MIDI
+properties -- such as different MIDI instruments -- set.
 
 
 @node Controlling MIDI dynamics
 @subsection Controlling MIDI dynamics
 
-MIDI dynamics are implemented by the Dynamic_performer which lives by
-default in the Voice context.  It is possible to control the overall
-MIDI volume, the relative volume of dynamic markings and the relative
-volume of different instruments.
+It is possible to control the overall MIDI volume, the relative volume
+of dynamic markings and the relative volume of different instruments.
+
+Dynamic marks translate automatically into volume levels in the
+available MIDI volume range whereas crescendi and decrescendi vary the
+volume linearly between their two extremes.  It is possible to control
+the relative volume of dynamic markings, and the overall volume levels
+of different instruments.
 
 @menu
-* Dynamic marks::
-* Overall MIDI volume::
-* Equalizing different instruments (i)::
-* Equalizing different instruments (ii)::
+* Dynamic marks in MIDI::
+* Setting MIDI volume::
+* Setting MIDI block properties::
 @end menu
 
-@node Dynamic marks
-@unnumberedsubsubsec Dynamic marks
-
-Dynamic marks are translated to a fixed fraction of the available MIDI
-volume range.  The default fractions range from 0.25 for
-@notation{ppppp} to 0.95 for @notation{fffff}.  The set of dynamic
-marks and the associated fractions can be seen in
-@file{../scm/midi.scm}, see @rlearning{Other sources of information}.
-This set of fractions may be changed or extended by providing a
-function which takes a dynamic mark as its argument and returns the
-required fraction, and setting
-@code{Score.dynamicAbsoluteVolumeFunction} to this function.
-
-For example, if a @notation{rinforzando} dynamic marking, @code{\rfz},
-is required, this will not by default have any effect on the MIDI
-volume, as this dynamic marking is not included in the default set.
-Similarly, if a new dynamic marking has been defined with
-@code{make-dynamic-script} that too will not be included in the default
-set.  The following example shows how the MIDI volume for such dynamic
-markings might be added.  The Scheme function sets the fraction to 0.9
-if a dynamic mark of @code{rfz} is found, or calls the default function
-otherwise.
+@cindex MIDI volume
+@cindex MIDI equalization
+@cindex MIDI dynamics
+@cindex Dynamics in MIDI
 
-@lilypond[verbatim,quote]
-#(define (myDynamics dynamic)
-    (if (equal? dynamic "rfz")
-      0.9
-      (default-dynamic-absolute-volume dynamic)))
 
-\score {
-  \new Staff {
-    \set Staff.midiInstrument = #"cello"
-    \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
-    \new Voice {
-      \relative c'' {
-        a4\pp b c-\rfz
-      }
-    }
-  }
-  \layout {}
-  \midi {}
-}
-@end lilypond
+@node Dynamic marks in MIDI
+@unnumberedsubsubsec Dynamic marks in MIDI
 
-Alternatively, if the whole table of fractions needs to be redefined, it
-would be better to use the @notation{default-dynamic-absolute-volume}
-procedure in @file{../scm/midi.scm} and the associated table as a model.
-The final example in this section shows how this might be done.
+Only the dynamic markings from @code{ppppp} to @code{fffff}, including
+@code{mp}, @code{mf} and @code{sf} have values assigned to them.  This
+value is then applied to the value of the overall MIDI volume range to
+obtain the final volume included in the MIDI output for that particular
+dynamic marking.  The default fractions range from 0.25 for
+@notation{ppppp} to 0.95 for @notation{fffff}. The complete set of
+dynamic marks and their associated fractions can be found in
+@file{scm/midi.scm}.
 
-@seealso
-Notation Reference:
-@ref{Expressive marks},
-@ref{Score layout}.
+
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{creating-custom-dynamics-in-midi-output.ly}
 
 Installed Files:
+@file{ly/script-init.ly}
 @file{scm/midi.scm}.
 
+Snippets:
+@rlsr{MIDI}.
+
 Internals Reference:
 @rinternals{Dynamic_performer}.
 
 
-
-@node Overall MIDI volume
-@unnumberedsubsubsec Overall MIDI volume
+@node Setting MIDI volume
+@unnumberedsubsubsec Setting MIDI volume
 
 The minimum and maximum overall volume of MIDI dynamic markings is
 controlled by setting the properties @code{midiMinimumVolume} and
@@ -3049,291 +2884,339 @@ midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
 @end example
 
 In the following example the dynamic range of the overall MIDI
-volume is limited to the range 0.2 - 0.5.
+volume is limited to the range @code{0.2} - @code{0.5}.
 
-@lilypond[verbatim,quote]
-\score {
+@example
+\score @{
   <<
-    \new Staff {
-      \key g \major
-      \time 2/2
+    \new Staff @{
       \set Staff.midiInstrument = #"flute"
-      \new Voice \relative c''' {
-        r2 g\mp g fis~
-        4 g8 fis e2~
-        4 d8 cis d2
-      }
-    }
-    \new Staff {
-      \key g \major
+      @var{@dots{} music @dots{}}
+    @}
+    \new Staff @{
       \set Staff.midiInstrument = #"clarinet"
-      \new Voice \relative c'' {
-        b1\p a2. b8 a
-        g2. fis8 e
-        fis2 r
-      }
-    }
+      @var{@dots{} music @dots{}}
+    @}
   >>
-  \layout {}
-  \midi {
-    \tempo 2 = 72
-    \context {
+  \midi @{
+    \context @{
       \Score
       midiMinimumVolume = #0.2
       midiMaximumVolume = #0.5
-    }
-  }
-}
-@end lilypond
-
-@seealso
-Notation Reference:
-@ref{Score layout}.
-
-Internals Reference:
-@rinternals{Dynamic_performer}.
-
-
+    @}
+  @}
+@}
+@end example
 
-@node Equalizing different instruments (i)
-@unnumberedsubsubsec Equalizing different instruments (i)
+Simple MIDI instrument equalization can be achieved by setting
+@code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
+the @code{Staff} context.
 
-If the minimum and maximum MIDI volume properties are set in the
-@code{Staff} context the relative volumes of the MIDI instruments can be
-controlled.  This gives a basic instrument equalizer, which can enhance
-the quality of the MIDI output remarkably.
+@example
+\score @{
+  \new Staff @{
+    \set Staff.midiInstrument = #"flute"
+    \set Staff.midiMinimumVolume = #0.7
+    \set Staff.midiMaximumVolume = #0.9
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
+@}
+@end example
 
-In this example the volume of the clarinet is reduced relative to the
-volume of the flute.
+For scores with multiple staves and multiple MIDI instruments, the
+relative volumes of each instrument can be set individually;
 
-@lilypond[verbatim,quote]
-\score {
+@example
+\score @{
   <<
-    \new Staff {
-      \key g \major
-      \time 2/2
+    \new Staff @{
       \set Staff.midiInstrument = #"flute"
       \set Staff.midiMinimumVolume = #0.7
       \set Staff.midiMaximumVolume = #0.9
-      \new Voice \relative c''' {
-        r2 g\mp g fis~
-        4 g8 fis e2~
-        4 d8 cis d2
-      }
-    }
-    \new Staff {
-      \key g \major
+      @var{@dots{} music @dots{}}
+    @}
+    \new Staff @{
       \set Staff.midiInstrument = #"clarinet"
       \set Staff.midiMinimumVolume = #0.3
       \set Staff.midiMaximumVolume = #0.6
-      \new Voice \relative c'' {
-        b1\p a2. b8 a
-        g2. fis8 e
-        fis2 r
-      }
-    }
+      @var{@dots{} music @dots{}}
+    @}
   >>
-  \layout {}
-  \midi {
-    \tempo 2 = 72
-  }
-}
-@end lilypond
+  \midi @{ @}
+@}
+@end example
+
+In this example the volume of the clarinet is reduced relative to the
+volume of the flute.
+
+If these volumes properties are not set then LilyPond still applies a
+@q{small degree} of equalization to certain instruments.  See
+@file{scm/midi.scm}.
+
+Installed Files:
+@file{scm/midi.scm}.
 
 @seealso
 Notation Reference:
 @ref{Score layout}.
 
+Internals Reference:
+@rinternals{Dynamic_performer}.
 
-@node Equalizing different instruments (ii)
-@unnumberedsubsubsec Equalizing different instruments (ii)
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{replacing-default-midi-instrument-equalization.ly}
 
-If the MIDI minimum and maximum volume properties are not set LilyPond
-will, by default, apply a small degree of equalization to a few
-instruments.  The instruments and the equalization applied are shown in
-the table @notation{instrument-equalizer-alist} in
-@file{../scm/midi.scm}.
+@knownissues
+Changes in the MIDI volume take place only on starting a note, so
+crescendi and decrescendi cannot affect the volume of a single note.
 
-This basic default equalizer can be replaced by setting
-@code{instrumentEqualizer} in the @code{Score} context to a new Scheme
-procedure which accepts a MIDI instrument name as its only argument and
-returns a pair of fractions giving the minimum and maximum volumes to be
-applied to that instrument.  This replacement is done in the same way as
-shown for resetting the @code{dynamicAbsoluteVolumeFunction} at the
-start of this section. The default equalizer,
-@notation{default-instrument-equalizer}, in @file{../scm/midi.scm} shows
-how such a procedure might be written.
 
-The following example sets the relative flute and clarinet volumes to
-the same values as the previous example.
+@node Setting MIDI block properties
+@unnumberedsubsubsec Setting MIDI block properties
 
-@lilypond[verbatim,quote]
-#(define my-instrument-equalizer-alist '())
+The @code{\midi} block can contain context rearrangements, new context
+definitions or code that sets the values of certain properties.
 
-#(set! my-instrument-equalizer-alist
-  (append
-    '(
-      ("flute" . (0.7 . 0.9))
-      ("clarinet" . (0.3 . 0.6)))
-    my-instrument-equalizer-alist))
+@example
+\score @{
+  @var{@dots{} music @dots{}}
+  \midi @{
+    \tempo 4 = 72
+  @}
+@}
+@end example
 
-#(define (my-instrument-equalizer s)
-  (let ((entry (assoc s my-instrument-equalizer-alist)))
-    (if entry
-      (cdr entry))))
+Here the tempo is set to 72 quarter-note beats per minute.  The tempo
+mark in the @code{\midi} block will not appear in the printed score.
+Although any other @code{\tempo} indications specified within the
+@code{\score} block will also be reflected in the MIDI output.
 
-\score {
-  <<
-    \new Staff {
-      \key g \major
-      \time 2/2
-      \set Score.instrumentEqualizer = #my-instrument-equalizer
-      \set Staff.midiInstrument = #"flute"
-      \new Voice \relative c''' {
-        r2 g\mp g fis~
-        4 g8 fis e2~
-        4 d8 cis d2
-      }
-    }
-    \new Staff {
-      \key g \major
-      \set Staff.midiInstrument = #"clarinet"
-      \new Voice \relative c'' {
-        b1\p a2. b8 a
-        g2. fis8 e
-        fis2 r
-      }
-    }
-  >>
-  \layout { }
-  \midi {
-    \tempo 2 = 72
-  }
-}
-@end lilypond
+In a @code{\midi} block the @code{\tempo} command is setting properties
+during the interpretation of the music and in the context of output
+definitions; so it is interpreted @emph{as if} it were a context
+modification.
+
+@cindex MIDI context definitions
+@cindex context definitions with MIDI
+
+Context definitions follow the same syntax as those in a @code{\layout}
+block;
+
+@example
+\score @{
+  @var{@dots{} music @dots{}}
+  \midi @{
+    \context @{
+      \Voice
+      \remove "Dynamic_performer"
+    @}
+  @}
+@}
+@end example
+
+This example removes the effect of dynamics from the MIDI output.  Note:
+LilyPond's translation modules used for sound are called @q{performers}.
+
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
 
 @seealso
+Learning Manual:
+@rlearning{Other sources of information}.
+
+Notation Reference:
+@ref{Expressive marks},
+@ref{Score layout}.
+
 Installed Files:
-@file{scm/midi.scm}.
+@file{ly/performer-init.ly}.
+
+Snippets:
+@rlsr{MIDI}.
 
 Internals Reference:
 @rinternals{Dynamic_performer}.
 
-@ignore
-@c Delete when satisfied this is adequately covered elsewhere -td
+@knownissues
+Some MIDI players do not always correctly handle tempo changes in the
+midi output.
 
-@n ode Microtones in MIDI
-@s ubsection Microtones in MIDI
+Changes to the @code{midiInstrument}, as well as some MIDI options, at
+the @emph{beginning} of a staff may appear twice in the MIDI output.
 
-@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' {
-    c4 cih cis cisih
-    d4 dih ees eeh
-    e4 eih f fih
-    fis4 fisih g gih
-    gis4 gisih a aih
-    bes4 beh b bih
-  }
-  \layout {}
-  \midi {}
-}
-@end lilypond
-@end ignore
+@node Using MIDI instruments
+@subsection Using MIDI instruments
 
+MIDI instruments are set using the @code{midiInstrument} property within
+a @code{Staff} context.
 
-@node Percussion in MIDI
-@subsection Percussion in MIDI
-
-Percussion instruments are generally notated in a @code{DrumStaff}
-context and when notated in this way they are outputted correctly to
-MIDI channel@tie{}10, but some pitched percussion instruments, like the
-xylophone, marimba, vibraphone, timpani, etc., are treated like
-@qq{normal} instruments and music for these instruments should be
-entered in a normal @code{Staff} context, not a @code{DrumStaff}
-context, to obtain the correct MIDI output.
+@example
+\score @{
+  \new Staff @{
+    \set Staff.midiInstrument = #"glockenspiel"
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
+@}
+@end example
 
-Some non-pitched percussion sounds included in the general MIDI
-standard, like melodic tom, taiko drum, synth drum, etc., cannot be
-reached via MIDI channel@tie{}10, so the notation for such instruments
-should also be entered in a normal @code{Staff} context, using suitable
-normal pitches.
+or
 
-Many percussion instruments are not included in the general MIDI
-standard, e.g. castanets.  The easiest, although unsatisfactory, method
-of producing some MIDI output when writing for such instruments is to
-substitute the nearest sound from the standard set.
+@example
+\score @{
+  \new Staff \with @{midiInstrument = #"cello"@} @{
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
+@}
+@end example
 
-@c TODO Expand with examples, and any other issues
+If the instrument name does not match any of the instruments listed in
+the @q{MIDI instruments} section, the @code{acoustic grand} instrument
+will be used instead. See @ref{MIDI instruments}.
 
 @seealso
+Learning Manual:
+@rlearning{Other sources of information}.
+
 Notation Reference:
-@ref{Percussion},
+@ref{MIDI instruments},
 @ref{Score layout}.
 
-Internals Reference:
-@rinternals{Dynamic_performer}.
+Installed Files:
+@file{scm/midi.scm}.
 
 @knownissues
-Because the general MIDI standard does not contain rim shots, the
-sidestick is used for this purpose instead.
+Percussion instruments that are notated in a @code{DrumStaff}
+context will be output, correctly, to MIDI channel@tie{}10 but some
+pitched, percussion instruments like the xylophone, marimba, vibraphone
+or timpani, are treated as @qq{normal} instruments so the music for
+these should be entered in a @code{Staff} (not @code{DrumStaff}) context
+to obtain correct MIDI output.  A full list of
+@code{channel 10 drum-kits} entries can be found in @file{scm/midi.scm}.
+See @rlearning{Other sources of information}.
 
 
+@node Using repeats with MIDI
+@subsection Using repeats with MIDI
+
+@cindex repeats in MIDI
+@cindex MIDI using repeats
+@funindex \unfoldRepeats
 
-@node The Articulate script
-@subsection The Articulate script
+Repeats can be represented in the MIDI output by applying the
+@code{\unfoldRepeats} command.
 
-A more realistic MIDI output is possible when using the Articulate
-script.  It tries to take articulations (slurs, staccato, etc) into
-account, by replacing notes with sequential music of suitably
-time-scaled note plus skip.  It also tries to unfold trills turns etc.,
-and take rallentando and accelerando into account.
+@example
+\score @{
+  \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' @}
+    @}
+  @}
+  \midi @{ @}
+@}
+@end example
 
-To use the Articulate script, you have to include it at the top of your
-input file,
+In order to restrict the effect of @code{\unfoldRepeats} to the MIDI
+output only, while also generating printable scores, it is necessary to
+make @emph{two} @code{\score} blocks; one for MIDI (with unfolded
+repeats) and one for the notation (with volta, tremolo, and percent
+repeats);
 
 @example
-\include "articulate.ly"
+\score @{
+  @var{@dots{} music @dots{}}
+  \layout @{ @}
+@}
+\score @{
+  \unfoldRepeats @{
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
+@}
 @end example
 
-and in the @code{\score} section do
+When using multiple voices, each of the voices must contain completely
+unfolded repeats for correct MIDI output.
+
+@seealso
+Notation Reference:
+@ref{Repeats}.
+
+
+@node Enhancing MIDI output
+@subsection Enhancing MIDI output
+
+@menu
+* The articulate script::
+@end menu
+
+The default MIDI output is basic but can be improved by setting MIDI
+instruments, @code{\midi} block properties and/or using the
+@file{articulate} script.
+
+@cindex instrument names
+@cindex MIDI, instruments
+@cindex articulate script
+@cindex articulate.ly
+@funindex Staff.midiInstrument
+
+
+@node The articulate script
+@unnumberedsubsubsec The @file{articulate} script
+
+To use the @file{articulate} script add the appropriate @code{\include}
+command at the top of the input file;
 
 @example
-\unfoldRepeats \articulate <<
-  all the rest of the score@dots{}
->>
+\include "articulate.ly"
 @end example
 
-After altering your input file this way, the visual output is heavily
-altered, but the standard @code{\midi} block will produce a better
-MIDI file.
+The script creates MIDI output into appropriately @q{time-scaled} notes
+to match many articulation and tempo indications.  Engraved output
+however, will also be altered to literally match the MIDI output.
 
-Although not essential for the Articulate script to work, you may want
-to insert the @code{\unfoldRepeats} command as it appears in the
-example shown above as it enables performing abbreviatures such as
-@notation{trills}.
+@example
+\score @{
+  \articulate <<
+    @var{@dots{} music @dots{}}
+  >>
+  \midi @{ @}
+@}
+@end example
+
+The @code{\articulate} command enables abbreviatures (such as trills and
+turns) to be processed.  A full list of supported items can be found in
+the script itself.  See @file{ly/articulate.ly}.
 
 @seealso
+Learning Manual:
+@rlearning{Other sources of information}.
+
 Notation Reference:
 @ref{Score layout}.
 
 Installed Files:
 @file{ly/articulate.ly}.
 
-Internals Reference:
-@rinternals{UnfoldedRepeatedMusic}.
+@warning{The @file{articulate} script may shorten chords, which might
+not be appropriate for some types of instrument, such as organ music.
+Notes that do not have any articulations attached to them may also be
+shortened; so to compensate for this, restrict the use of the
+@code{\articulate} function to shorter segments of music or modify the
+values of the variables defined in the @file{articulate} script to
+compenstate for the note-shortening behavior.}
 
-@knownissues
-Articulate shortens chords and some music (esp. organ music) could
-sound worse.
 
 
 @node Extracting musical information
@@ -3366,7 +3249,7 @@ line.  For example,
 will display
 
 @example
-@{ a,4 cis e fis g @}
+@{ a,4 cis4 e4 fis4 g4 @}
 @end example
 
 By default, LilyPond will print these messages to the console