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

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index fc2ead626d..83d18c5c06 100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.19.2"
+@c \version "2.19.22"
 
 @node General input and output
 @chapter General input and output
@@ -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
 
@@ -228,7 +228,7 @@ input file, LilyPond will implicitly treat the whole
 file as a single \book block, see
 @ref{File structure}.
 
-When producing multiple files from a single source file, Lilypond
+When producing multiple files from a single source file, LilyPond
 ensures that none of the output files from any @code{\book} block
 overwrites the output file produced by a preceding @code{\book} from
 the same input file.
@@ -273,11 +273,11 @@ will produce
 @funindex \bookOutputSuffix
 @funindex \bookOutputName
 
-Lilypond provides facilities to allow you to control what file names
+LilyPond provides facilities to allow you to control what file names
 are used by the various back-ends when producing output files.
 
-In the previous section, we saw how Lilypond prevents name-clashes when
-producing several ouputs from a single source file.  You also have the
+In the previous section, we saw how LilyPond prevents name-clashes when
+producing several outputs from a single source file.  You also have the
 ability to specify your own suffixes for each @code{\book} block, so
 for example you can produce files called
 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
@@ -365,9 +365,9 @@ A direct scheme expression, such as
 @code{#(ly:set-option 'point-and-click #f)}.
 
 @item
-A @code{\header} block.  This sets the global (i.e. the top of
+A @code{\header} block.  This sets the global (i.e., the top of
 file) header block.  This is the block containing the default
-settings of titling fields like composer, title, etc. for all
+settings of titling fields like composer, title, etc., for all
 books within the file (see @ref{Titles explained}).
 
 @item
@@ -496,11 +496,11 @@ circumstances to avoid errors:
 
 @item Around every opening and closing curly bracket.
 
-@item After every command or variable, i.e. every item that
+@item After every command or variable, i.e., every item that
 begins with a @code{\} sign.
 
 @item After every item that is to be interpreted as a Scheme
-expression, i.e. every item that begins with a @code{#}@tie{}sign.
+expression, i.e., every item that begins with a @code{#}@tie{}sign.
 
 @item To separate all elements of a Scheme expression.
 
@@ -521,12 +521,17 @@ Notation Reference:
 @node Titles and headers
 @section Titles and headers
 
+@cindex titles
+@cindex headers
+@cindex footers
+
 Almost all printed music includes a title and the composer's name;
 some pieces include a lot more information.
 
 @menu
 * Creating titles headers and footers::
 * Custom titles headers and footers::
+* Creating output file metadata::
 * Creating footnotes::
 * Reference to page numbers::
 * Table of contents::
@@ -643,10 +648,10 @@ suitable, as here:
 }
 
 \score {
-  \new Staff \relative g, {
+  \new Staff \relative {
     \clef bass
     \key g \major
-    \repeat unfold 2 { g16( d' b') a b d, b' d, } |
+    \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
     \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
   }
   \header {
@@ -655,7 +660,7 @@ suitable, as here:
 }
 
 \score {
-  \new Staff \relative b {
+  \new Staff \relative {
     \clef bass
     \key g \major
     \partial 16 b16 |
@@ -681,7 +686,7 @@ suppressed:
   \header {
     title = "DAS WOHLTEMPERIRTE CLAVIER"
     subtitle = "TEIL I"
-    % Do not display the tagline for this book
+    % Do not display the default LilyPond footer for this book
     tagline = ##f
   }
   \markup { \vspace #1 }
@@ -723,7 +728,7 @@ Notation Reference:
 @node Default layout of bookpart and score titles
 @unnumberedsubsubsec Default layout of bookpart and score titles
 
-This example demonstrates all @code{\header} variables:
+This example demonstrates all printed @code{\header} variables:
 
 @lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
 \book {
@@ -742,8 +747,8 @@ This example demonstrates all @code{\header} variables:
     meter = "Meter"
     arranger = "Arranger"
       % The following fields are centered at the bottom
-    tagline = "tagline goes at the bottom of the last page"
-    copyright = "copyright goes at the bottom of the first page"
+    tagline = "The tagline goes at the bottom of the last page"
+    copyright = "The copyright goes at the bottom of the first page"
   }
   \score {
     { s1 }
@@ -875,8 +880,8 @@ the @code{copyright} text if there is only a single page.
 
 @end itemize
 
-The default tagline can be changed by adding a @code{tagline} in the
-top-level @code{\header} block.
+The default LilyPond footer text can be changed by adding a
+@code{tagline} in the top-level @code{\header} block.
 
 @lilypond[papersize=a8landscape,verbatim]
 \book {
@@ -884,14 +889,15 @@ top-level @code{\header} block.
     tagline = "... music notation for Everyone"
   }
   \score {
-    \relative c' {
-      c4 d e f
+    \relative {
+      c'4 d e f
     }
   }
 }
 @end lilypond
 
-To remove the @code{tagline} set the value to @code{##f}.
+To remove the default LilyPond footer text, the @code{tagline} can be
+set to @code{##f}.
 
 
 @node Custom titles headers and footers
@@ -1113,16 +1119,16 @@ markup conditionally to header and footer text defined within the
 @code{\paper} block, using the following syntax:
 
 @example
-@code{variable} = @code{\markup} @{
+variable = \markup @{
   @dots{}
-  @code{\on-the-fly}  \@var{procedure}  @var{markup}
+  \on-the-fly  \@var{procedure}  @var{markup}
   @dots{}
 @}
 @end example
 
 The @var{procedure} is called each time the @code{\markup} command
 in which it appears is evaluated.  The @var{procedure} should test
-for a particular condition and interpret (i.e. print) the
+for a particular condition and interpret (i.e., print) the
 @var{markup} argument if and only if the condition is true.
 
 A number of ready-made procedures for testing various conditions are
@@ -1137,10 +1143,11 @@ provided:
 @item create-page-number-stencil    @tab  print-page-numbers true?
 @item print-all-headers             @tab  print-all-headers true?
 @item first-page                    @tab  first page in the book?
+@item not-first-page                @tab  not first page in the book?
 @item (on-page nmbr)                @tab  page number = nmbr?
 @item last-page                     @tab  last page in the book?
-@item not-first-page                @tab  not first page in the book?
 @item part-first-page               @tab  first page in the book part?
+@item not-part-first-page           @tab  not first page in the book part?
 @item part-last-page                @tab  last page in the book part?
 @item not-single-page               @tab  pages in book part > 1?
 
@@ -1179,8 +1186,8 @@ Several @code{\on-the-fly} conditions can be combined with an
 @q{and} operation, for example,
 
 @example
-  @code{\on-the-fly \first-page}
-  @code{\on-the-fly \last-page}
+  \on-the-fly \first-page
+  \on-the-fly \last-page
   @code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
 @end example
 
@@ -1194,6 +1201,57 @@ Notation Reference:
 Installed Files:
 @file{../ly/titling-init.ly}.
 
+@node Creating output file metadata
+@subsection Creating output file metadata
+
+@cindex PDF metadata
+@cindex MIDI metadata
+
+In addition to being shown in the printed output, @code{\header} variables
+are also used to set metadata for output files.  For example, with PDF
+files, this metadata could be displayed by PDF readers as the
+@code{properties} of the PDF file.  For each type of output file, only the
+@code{\header} definitions of blocks that define separate files of that
+type, and blocks higher in the block hierarchy, will be consulted.
+Therefore, for PDF files, only the @code{\book} level and the top level
+@code{\header} definitions affect the document-wide PDF metadata, whereas
+for MIDI files, all headers above or at the @code{\score} level are used.
+
+For example, setting the @code{title} property of the @code{header} block
+to @q{Symphony I} will also give this title to the PDF document, and use
+it as the sequence name of the MIDI file.
+
+@example
+\header@{
+  title = "Symphony I"
+@}
+@end example
+
+If you want to set the title of the printed output to one value, but have the
+title property of the PDF to have a different value, you can use
+@code{pdftitle}, as below.
+
+@example
+\header@{
+  title = "Symphony I"
+  pdftitle = "Symphony I by Beethoven"
+@}
+@end example
+
+The variables @code{title}, @code{subject}, @code{keywords},
+@code{subtitle}, @code{composer}, @code{arranger}, @code{poet}, @code{author}
+and @code{copyright} all set PDF properties and can all be prefixed with
+@q{pdf} to set a PDF property to a value different from the printed output.
+
+The PDF property @code{Creator} is automatically set to @q{LilyPond} plus
+the current LilyPond version, and @code{CreationDate} and @code{ModDate} are
+both set to the current date and time.  @code{ModDate} can be overridden by
+setting the header variable @code{moddate} (or @code{pdfmoddate}) to a
+valid PDF date string.
+
+The @code{title} variable sets also the sequence name for MIDI.  The
+@code{midititle} variable can be used to set the sequence name
+independently of the value used for typeset output.
 
 @node Creating footnotes
 @subsection Creating footnotes
@@ -1281,9 +1339,9 @@ left/bottom edge and zero implies the mark is centered on the edge.
 
 @item Context
 is the context in which the grob being footnoted is created.  It
-may be omitted if the grob is in a bottom context, e.g. a
+may be omitted if the grob is in a bottom context, e.g., a
 @code{Voice} context.
- 
+
 @item GrobName
 specifies a type of grob to mark (like @samp{Flag}).  If it is
 specified, the footnote is not attached to a music expression in
@@ -1354,8 +1412,8 @@ is:
 @lilypond[quote,verbatim,papersize=a8landscape]
 \book {
   \header { tagline = ##f }
-  \relative c'' {
-    a4_\footnote #'(0 . -1) "A slur forced down" (
+  \relative {
+    a'4_\footnote #'(0 . -1) "A slur forced down" (
     b8^\footnote #'(1 . 0.5) "A manual beam forced up" [
     b8 ]
     c4 )
@@ -1537,7 +1595,7 @@ For example:
     \auto-footnote "recent" \italic " Aug 2012"
     "composition."
   }
-  \relative c' {
+  \relative {
     a'4 b8 e c4 d
   }
 }
@@ -1583,7 +1641,7 @@ aliases may be used (see @ref{ASCII aliases}):
     }
     "composition."
   }
-  \relative c' {
+  \relative {
     a'4 b8 e c4 d
   }
 }
@@ -1606,7 +1664,7 @@ Unicode character codes may also be used to specify marks
     }
     "composition."
   }
-  \relative c' {
+  \relative {
     a'4 b8 e c4 d
   }
 }
@@ -1693,10 +1751,11 @@ ie. a two digit number.
 
 @node Table of contents
 @subsection Table of contents
-A table of contents is included using the @code{\markuplist \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.
+A table of contents is included using the
+@code{\markuplist \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
 \markuplist \table-of-contents
@@ -1719,39 +1778,89 @@ top-level, or inside a music expression.
 }
 @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:
+Markups used for formatting the table of contents are defined in the
+@code{\paper} block.  There are two @q{pre-defined} markups already
+available;
+
+@itemize
+
+@item
+@code{tocTitleMarkup}
+
+@noindent
+Used for formatting the title of the table of contents.
+
+@verbatim
+tocTitleMarkup = \markup \huge \column {
+  \fill-line { \null "Table of Contents" \null }
+  \null
+}
+@end verbatim
+
+@item
+@code{tocItemMarkup}
+
+@noindent
+Used for formatting the elements within the table of contents.
+
+@verbatim
+tocItemMarkup = \markup \fill-line {
+  \fromproperty #'toc:text \fromproperty #'toc:page
+}
+@end verbatim
+
+@end itemize
+
+@noindent
+Both of these variables can be changed.
+
+Here is an example changing the table of contents' title into French;
 
 @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
+
+Here is an example changing the font-size of the elements in the table
+of contents;
+
+@verbatim
+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.
+Note how the element text and page numbers 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
+The @code{\tocItemWithDotsMarkup} command can be included within the
+@code{tocItemMarkup} to fill the line, between a table of contents item
+and its corresponding page number, with dots;
+
+@lilypond[verbatim,line-width=10.0\cm]
+\header { tagline = ##f }
+\paper {
+  tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+  \markuplist \table-of-contents
+  \tocItem \markup { Allegro }
+  \tocItem \markup { Largo }
+  \markup \null
+}
+@end lilypond
+
+Custom commands with their own markups can also be defined to build a
+more complex table of contents.  In the following example, a new style
+is defined for entering act names in a table of contents of an opera;
 
-In the following example, a new style is defined for entering act names
-in the table of contents of an opera:
+@noindent
+A new markup variable (called @code{tocActMarkup}) is defined in the
+@code{\paper} block;
 
 @verbatim
 \paper {
@@ -1761,12 +1870,22 @@ in the table of contents of an opera:
     \hspace #1
   }
 }
+@end verbatim
+
+@noindent
+A custom music function (@code{tocAct}) is then created -- which uses
+the new @code{tocActMarkup} markup definition.
 
+@verbatim
 tocAct =
-#(define-music-function (parser location text) (markup?)
-   (add-toc-item! 'tocActMarkup text))
+  #(define-music-function (text) (markup?)
+     (add-toc-item! 'tocActMarkup text))
 @end verbatim
 
+@noindent
+A LilyPond input file, using these customer definitions, could look
+something like this;
+
 @lilypond[line-width=10.0\cm]
 \header { tagline = ##f }
 \paper {
@@ -1778,14 +1897,14 @@ tocAct =
 }
 
 tocAct =
-#(define-music-function (parser location text) (markup?)
+#(define-music-function (text) (markup?)
    (add-toc-item! 'tocActMarkup text))
 
 \book {
   \markuplist \table-of-contents
   \tocAct \markup { Atto Primo }
   \tocItem \markup { Coro. Viva il nostro Alcide }
-  \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
+  \tocItem \markup { Cesare. Presti omai l'Egizia terra }
   \tocAct \markup { Atto Secondo }
   \tocItem \markup { Sinfonia }
   \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
@@ -1793,21 +1912,19 @@ tocAct =
 }
 @end lilypond
 
-Dots can be added to fill the line between an item and its page number:
 
-@lilypond[verbatim,line-width=10.0\cm]
-\header { tagline = ##f }
-\paper {
-  tocItemMarkup = \tocItemWithDotsMarkup
-}
+Here is an example of the @code{\fill-with-pattern} command used within
+the context of a table of contents;
 
-\book {
-  \markuplist \table-of-contents
-  \tocItem \markup { Allegro }
-  \tocItem \markup { Largo }
-  \markup \null
+@verbatim
+\paper {
+  tocItemMarkup = \markup { \fill-line {
+    \override #'(line-width . 70)
+    \fill-with-pattern #1.5 #CENTER . \fromproperty #'toc:text \fromproperty #'toc:page
+    }
+  }
 }
-@end lilypond
+@end verbatim
 
 @seealso
 Installed Files:
@@ -2019,11 +2136,11 @@ 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 }
+sopranoMusic = \relative { a'4 b c b8( a) }
+altoMusic = \relative { e'4 e e f }
+tenorMusic = \relative { c'4 b e d8( c) }
+bassMusic = \relative { a4 gis a d, }
+allLyrics = \lyricmode { King of glo -- ry }
 <<
   \new Staff = "Soprano" \sopranoMusic
   \new Lyrics \allLyrics
@@ -2041,17 +2158,11 @@ allLyrics = \lyricmode {King of glo -- ry }
   \new Lyrics \allLyrics
   \new PianoStaff <<
     \new Staff = "RH" {
-      \set Staff.printPartCombineTexts = ##f
-      \partcombine
-      \sopranoMusic
-      \altoMusic
+      \partcombine \sopranoMusic \altoMusic
     }
     \new Staff = "LH" {
-      \set Staff.printPartCombineTexts = ##f
       \clef "bass"
-      \partcombine
-      \tenorMusic
-      \bassMusic
+      \partcombine \tenorMusic \bassMusic
     }
   >>
 >>
@@ -2071,12 +2182,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 +2199,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,17 +2214,23 @@ 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
 explicitly expanded:
 
 @lilypond[verbatim,quote]
-music = \relative g' {
-  g8. c32 d
+music = \relative {
+  g'8. c32 d
   \tag #'trills { d8.\trill }
   \tag #'expand { \repeat unfold 3 { e32 d } }
   c32 d
@@ -2134,8 +2248,8 @@ music = \relative g' {
 Alternatively, it is sometimes easier to exclude sections of music:
 
 @lilypond[verbatim,quote]
-music = \relative g' {
-  g8. c32 d
+music = \relative {
+  g'8. c32 d
   \tag #'trills { d8.\trill }
   \tag #'expand {\repeat unfold 3 { e32 d } }
   c32 d
@@ -2151,7 +2265,7 @@ music = \relative g' {
 }
 @end lilypond
 
-Tagged filtering can be applied to articulations, texts, etc. by
+Tagged filtering can be applied to articulations, texts, etc., by
 prepending
 
 @example
@@ -2185,8 +2299,8 @@ music = \relative c'' {
 
 Multiple @code{\removeWithTag} filters may be applied to a single
 music expression to remove several differently named tagged
-sections.  Alternatively, you can use a single
-@code{\removeWithTag} with a list of tags.
+sections.  Alternatively, you can use a single @code{\removeWithTag}
+with a list of tags.
 
 @lilypond[verbatim,quote]
 music = \relative c'' {
@@ -2204,13 +2318,77 @@ music = \relative c'' {
 }
 @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.
-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.
+Using two or more @code{\keepWithTag} filters on a single music
+expression will cause @emph{all} of the tagged sections to be removed.
+The first filter will remove all except the one named and any subsequent
+filters will remove the rest.  Using one @code{\keepWithTag} command
+with a list of multiple tags will only remove tagged sections that are
+not specified in that list.
+
+@lilypond[verbatim,quote]
+music = \relative c'' {
+  \tag #'violinI { a4 a a a }
+  \tag #'violinII { b4 b b b }
+  \tag #'viola { c4 c c c }
+  \tag #'cello { d4 d d d }
+}
+
+\new Staff {
+  \keepWithTag #'(violinI violinII)
+  \music
+}
+@end lilypond
+
+@noindent
+will print @code{\tag}s @var{violinI} and @var{violinII} but not
+@var{viola} or @var{cello}.
+
+@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 them for more than one purpose.  In that case
+@q{groups} of tags can be declared:
+
+@example
+\tagGroup #'(violinI violinII viola cello)
+@end example
+
+@noindent
+Now all the different tags belong to a single @q{tag group}.  Note that
+individual tags cannot be members of more than one @emph{tag group}.
+
+@example
+\keepWithTag #'violinI @dots{}
+@end example
+
+@noindent
+will now only show music tagged from @code{violinI}'s tag group and any
+music tagged with one of the @emph{other} tags will removed.
+
+@lilypond[verbatim,quote]
+music = \relative {
+  \tagGroup #'(violinI violinII viola cello)
+  \tag #'violinI { c''4^"violinI" c c c }
+  \tag #'violinII { a2 a }
+  \tag #'viola { e8 e e2. }
+  \tag #'cello { d'2 d4 d }
+  R1^"untagged"
+}
+
+\new Voice {
+  \keepWithTag #'violinI
+  \music
+}
+@end lilypond
+
+When using the @code{\keepWithTag} command, only tags from the tag
+groups of the tags given in the command are visible.
+
+@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
@@ -2220,22 +2398,20 @@ construct has @code{elements}, but sequential and simultaneous music are
 safe bets:
 
 @lilypond[verbatim,quote]
-test = { \tag #'here { \tag #'here <<c''>> } }
+music = { \tag #'here { \tag #'here <<c''>> } }
 
 {
   \pushToTag #'here c'
   \pushToTag #'here e'
-  \pushToTag #'here g' \test
+  \pushToTag #'here g' \music
   \appendToTag #'here c'
   \appendToTag #'here e'
-  \appendToTag #'here g' \test
+  \appendToTag #'here g' \music
 }
 @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:
@@ -2322,7 +2498,7 @@ 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
+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.
@@ -2339,8 +2515,20 @@ will be generated.
 Here is an example showing Cyrillic, Hebrew and Portuguese
 text:
 
+@c NOTE: No verbatim in the following example as the code does not
+@c display correctly in PDF Font settings for Cyrillic and Hebrew
+
 @lilypond[quote]
-%c No verbatim here as the code does not display correctly in PDF
+% Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
+\paper {
+  #(define fonts
+    (set-global-fonts
+     #:roman "Linux Libertine O,serif"
+     #:sans "Linux Biolinum O,sans-serif"
+     #:typewriter "Linux Libertine Mono O,monospace"
+   ))
+}
+
 % Cyrillic
 bulgarian = \lyricmode {
   Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
@@ -2356,8 +2544,8 @@ portuguese = \lyricmode {
   à vo -- cê uma can -- ção legal
 }
 
-\relative c' {
-  c2 d e f g f e
+\relative {
+  c'2 d e f g f e
 }
 \addlyrics { \bulgarian }
 \addlyrics { \hebrew }
@@ -2399,13 +2587,13 @@ lyrics and as stand-alone text below the score:
 
 @lilypond[quote,verbatim]
 \score {
-  \relative c'' {
-    c1 \mark \markup { \char ##x03EE }
+  \relative {
+    c''1 \mark \markup { \char ##x03EE }
     c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
   }
   \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 +2669,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 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 output 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
@@ -2540,7 +2742,7 @@ 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.  When working on the
-beginning of a score you have already typeset (e.g. to add a new part),
+beginning of a score you have already typeset (e.g., to add a new part),
 the @code{showFirstLength} property may be useful as well.
 
 Skipping parts of a score can be controlled in a more fine-grained
@@ -2551,12 +2753,15 @@ 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,relative=2,ragged-right,verbatim]
-c8 d
-\set Score.skipTypesetting = ##t
-e8 e e e e e e e
-\set Score.skipTypesetting = ##f
-c8 d b bes a g c2
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+  c1
+  \set Score.skipTypesetting = ##t
+  \tempo 4 = 80
+  c4 c c c
+  \set Score.skipTypesetting = ##f
+  d4 d d d
+}
 @end lilypond
 
 In polyphonic music, @code{Score.skipTypesetting} will affect all
@@ -2571,11 +2776,10 @@ voices and staves, saving even more time.
 @cindex EPS output
 
 The default output formats for the printed score are Portable
-Document Format (PDF) and PostScript (PS).  Scalable Vector
-Graphics (SVG), Encapsulated PostScript (EPS) and Portable
-Network Graphics (PNG) output formats are also available through
-command line options, see
-@rprogram{Basic command line options for LilyPond}.
+Document Format (PDF) and PostScript (PS).  Portable
+Network Graphics (PNG), Scalable Vector Graphics (SVG) and Encapsulated
+PostScript (EPS) output is available through the command line option,
+see @rprogram{Basic command line options for LilyPond}.
 
 
 @node Replacing the notation font
@@ -2618,722 +2822,769 @@ 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.
-
-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.
+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.
 
-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::
+* MIDI channel mapping::
+* Context properties for MIDI effects::
+* 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;
+@cindex MIDI, Supported notation
 
-@example
-\score @{
-  @var{@dots{}music@dots{}}
-  \layout @{ @}
-  \midi @{ @}
-@}
-@end example
+@node Supported notation for MIDI
+@subsection Supported notation for MIDI
 
-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.
+The following musical notation can be used with LilyPond's default
+capabilities to produce MIDI output;
 
-@example
-\score @{
-  @var{@dots{}music@dots{}}
-  \midi @{ @}
-@}
-@end example
+@itemize
+@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 @q{Simple} articulations; staccato, staccatissimo, accent, marcato
+and portato
+@item Tempo changes using the @code{\tempo} function
+@item Ties
+@item Tremolos that are @emph{not} entered with a
+@q{@code{:}[@var{number}]} value
+@end itemize
 
-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.
+Panning, balance, expression, reverb and chorus effects can also be
+controlled by setting context properties,
+see @ref{Context properties for MIDI effects}.
 
-All @code{\tempo} indications, including all subsequent tempo changes,
-specified within the music notation will be reflected in the MIDI
-output.
+When combined with the @file{articulate} script the following,
+additional musical notation can be output to MIDI;
 
-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.
+@itemize
+@item Appoggiaturas.  These are made to take half the value of the note
+following (without taking dots into account).  For example;
 
 @example
-\score @{
-  @var{@dots{}music@dots{}}
-  \midi @{
-    \tempo 4 = 72
-  @}
-@}
+\appoggiatura c8 d2.
 @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
+@noindent
+The c will take the value of a crotchet.
 
-Context definitions follow the same syntax as those in a @code{\layout}
-block;
+@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
 
-@example
-\score @{
-  @var{@dots{}music@dots{}}
-  \midi @{
-    \context @{
-      \Voice
-      \remove "Dynamic_performer"
-    @}
-  @}
-@}
-@end example
+@noindent
+See @ref{Enhancing MIDI output}.
 
-removes the effect of dynamics from the MIDI output.  Translation
-modules for sound are called @q{performers}.
+@cindex MIDI, Unsupported notation
 
-@snippets
-@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
+@node Unsupported notation for MIDI
+@subsection Unsupported notation for MIDI
 
-@seealso
-Learning Manual:
-@rlearning{Other sources of information}.
+The following items of musical notation cannot be output to MIDI;
 
-Notation Reference:
-@ref{Expressive marks},
-@ref{Score layout}.
+@itemize
+@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 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
 
-Installed Files:
-@file{ly/performer-init.ly}.
 
-Snippets:
-@rlsr{MIDI}.
+@node The MIDI block
+@subsection The MIDI block
 
-Internals Reference:
-@rinternals{Dynamic_performer}.
+@cindex MIDI block
 
-@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;
+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;
 
 @example
-#(ly:set-option 'midi-extension "mid")
+\score @{
+  @var{@dots{} music @dots{}}
+  \layout @{ @}
+  \midi @{ @}
+@}
 @end example
 
-This will set the default extension for MIDI files to @code{.mid}.
+@warning{A @code{@bs{}score} block that, as well as the music, contains
+only a @code{@bs{}midi} block (i.e., @emph{without} the @code{@bs{}layout}
+block), will only produce MIDI output files.  No notation will be
+printed.}
 
-Alternatively, an option can be supplied on the command line:
+The default output file extension (@code{.midi}) can be changed by using
+the @code{-dmidi-extension} option with the @code{lilypond} command:
 
 @example
 lilypond -dmidi-extension=mid MyFile.ly
 @end example
 
-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.
-
-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
+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
-\new Staff \with @{midiInstrument = #"cello"@} @{
-  @var{@dots{}notes@dots{}}
-@}
+#(ly:set-option 'midi-extension "mid")
 @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}.
+@ref{File structure},
+@ref{Creating output file metadata}.
 
-Internals Reference:
-@rinternals{Dynamic_performer}.
+Installed Files:
+@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 What goes into the MIDI output?
-@subsection What goes into the MIDI output?
 
-@c TODO Check grace notes - timing is suspect?
+@node Controlling MIDI dynamics
+@subsection Controlling MIDI dynamics
 
-@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:
+It is possible to control the overall MIDI volume, the relative volume
+of dynamic markings and the relative volume of different instruments.
 
-@itemize
-@item Pitches
-@item Microtones (See @ref{Accidentals}.  Rendering needs a
-player that supports pitch bend.)
-@item Chords entered as chord names
-@item Rhythms entered as note durations, including tuplets
-@item Tremolos entered without @q{@code{:}[@var{number}]}
-@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}
-@end itemize
+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.
 
-There is a script that adds the following items; see
-@ref{The Articulate script}:
+@menu
+* Dynamic marks in MIDI::
+* Setting MIDI volume::
+* Setting MIDI block properties::
+@end menu
 
-@itemize
-@item Slurs and phrasing slurs
-@item Ornaments (mordents, trills, turns, etc.)
-@item Rallentando, accelerando, ritard, and a tempo
-@end itemize
+@cindex MIDI volume
+@cindex MIDI equalization
+@cindex MIDI dynamics
+@cindex Dynamics in MIDI
 
-@seealso
-Notation Reference:
-@ref{Accidentals},
-@ref{Breath marks},
-@ref{Expressive marks}.
 
-Installed Files:
-@file{ly/articulate.ly}.
+@node Dynamic marks in MIDI
+@unnumberedsubsubsec Dynamic marks in MIDI
 
+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}.
 
-@node Unsupported in MIDI
-@unnumberedsubsubsec Unsupported in MIDI
 
-@c TODO index as above
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{creating-custom-dynamics-in-midi-output.ly}
 
-The following items of notation have no effect on the MIDI output, even
-if you use @ref{The Articulate script}:
+Installed Files:
+@file{ly/script-init.ly}
+@file{scm/midi.scm}.
 
-@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 Figured bass
-@item Microtonal chords
-@item Glissandi, falls and doits
-@end itemize
+Snippets:
+@rlsr{MIDI}.
 
-@seealso
-Installed Files:
-@file{ly/articulate.ly}.
+Internals Reference:
+@rinternals{Dynamic_performer}.
 
 
-@node Repeats in MIDI
-@subsection Repeats in MIDI
+@node Setting MIDI volume
+@unnumberedsubsubsec Setting MIDI volume
 
-@cindex repeats in MIDI
-@funindex \unfoldRepeats
+The minimum and maximum overall volume of MIDI dynamic markings is
+controlled by setting the properties @code{midiMinimumVolume} and
+@code{midiMaximumVolume} at the @code{Score} level.  These properties
+have an effect only at the start of a voice and on dynamic marks.  The
+fraction corresponding to each dynamic mark is modified with this
+formula
 
-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
+midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
+@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
+In the following example the dynamic range of the overall MIDI
+volume is limited to the range @code{0.2} - @code{0.5}.
 
-In scores containing multiple voices, unfolding of repeats in MIDI
-output will only occur correctly if @emph{each} voice contains fully
-notated repeat indications.
+@example
+\score @{
+  <<
+    \new Staff @{
+      \set Staff.midiInstrument = #"flute"
+      @var{@dots{} music @dots{}}
+    @}
+    \new Staff @{
+      \set Staff.midiInstrument = #"clarinet"
+      @var{@dots{} music @dots{}}
+    @}
+  >>
+  \midi @{
+    \context @{
+      \Score
+      midiMinimumVolume = #0.2
+      midiMaximumVolume = #0.5
+    @}
+  @}
+@}
+@end example
 
-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):
+Simple MIDI instrument equalization can be achieved by setting
+@code{midiMinimumVolume} and @code{midiMaximumVolume} properties within
+the @code{Staff} context.
 
 @example
 \score @{
-  @var{@dots{}music@dots{}}
-  \layout @{ @dots{} @}
+  \new Staff @{
+    \set Staff.midiInstrument = #"flute"
+    \set Staff.midiMinimumVolume = #0.7
+    \set Staff.midiMaximumVolume = #0.9
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
 @}
+@end example
+
+For scores with multiple staves and multiple MIDI instruments, the
+relative volumes of each instrument can be set individually;
+
+@example
 \score @{
-  \unfoldRepeats @var{@dots{}music@dots{}}
-  \midi @{ @dots{} @}
+  <<
+    \new Staff @{
+      \set Staff.midiInstrument = #"flute"
+      \set Staff.midiMinimumVolume = #0.7
+      \set Staff.midiMaximumVolume = #0.9
+      @var{@dots{} music @dots{}}
+    @}
+    \new Staff @{
+      \set Staff.midiInstrument = #"clarinet"
+      \set Staff.midiMinimumVolume = #0.3
+      \set Staff.midiMaximumVolume = #0.6
+      @var{@dots{} music @dots{}}
+    @}
+  >>
+  \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}.
 
-Installed Files:
-@file{ly/articulate.ly}.
+Internals Reference:
+@rinternals{Dynamic_performer}.
 
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{replacing-default-midi-instrument-equalization.ly}
 
-@node Controlling MIDI dynamics
-@subsection Controlling MIDI dynamics
+@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.
 
-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.
 
-@menu
-* Dynamic marks::
-* Overall MIDI volume::
-* Equalizing different instruments (i)::
-* Equalizing different instruments (ii)::
-@end menu
+@node Setting MIDI block properties
+@unnumberedsubsubsec Setting MIDI block properties
 
-@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.
+The @code{\midi} block can contain context rearrangements, new context
+definitions or code that sets the values of certain properties.
 
-@lilypond[verbatim,quote]
-#(define (myDynamics dynamic)
-    (if (equal? dynamic "rfz")
-      0.9
-      (default-dynamic-absolute-volume dynamic)))
+@example
+\score @{
+  @var{@dots{} music @dots{}}
+  \midi @{
+    \tempo 4 = 72
+  @}
+@}
+@end example
 
-\score {
-  \new Staff {
-    \set Staff.midiInstrument = #"cello"
-    \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
-    \new Voice {
-      \relative c'' {
-        a4\pp b c-\rfz
-      }
-    }
-  }
-  \layout {}
-  \midi {}
-}
-@end lilypond
+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.
+
+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
 
-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.
+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}.
 
 @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}.
 
+@knownissues
+Some MIDI players do not always correctly handle tempo changes in the
+midi output.
 
+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.
 
-@node Overall MIDI volume
-@unnumberedsubsubsec Overall MIDI volume
 
-The minimum and maximum overall volume of MIDI dynamic markings is
-controlled by setting the properties @code{midiMinimumVolume} and
-@code{midiMaximumVolume} at the @code{Score} level.  These properties
-have an effect only at the start of a voice and on dynamic marks.  The
-fraction corresponding to each dynamic mark is modified with this
-formula
+
+@node Using MIDI instruments
+@subsection Using MIDI instruments
+
+MIDI instruments are set using the @code{midiInstrument} property within
+a @code{Staff} context.
 
 @example
-midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
+\score @{
+  \new Staff @{
+    \set Staff.midiInstrument = #"glockenspiel"
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
+@}
 @end example
 
-In the following example the dynamic range of the overall MIDI
-volume is limited to the range 0.2 - 0.5.
+or
 
-@lilypond[verbatim,quote]
-\score {
-  <<
-    \new Staff {
-      \key g \major
-      \time 2/2
-      \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
-    \context {
-      \Score
-      midiMinimumVolume = #0.2
-      midiMaximumVolume = #0.5
-    }
-  }
-}
-@end lilypond
+@example
+\score @{
+  \new Staff \with @{midiInstrument = #"cello"@} @{
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
+@}
+@end example
+
+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{MIDI instruments},
 @ref{Score layout}.
 
-Internals Reference:
-@rinternals{Dynamic_performer}.
+Installed Files:
+@file{scm/midi.scm}.
 
+@knownissues
+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 Equalizing different instruments (i)
-@unnumberedsubsubsec Equalizing different instruments (i)
+@node Using repeats with MIDI
+@subsection Using repeats with MIDI
 
-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.
+@cindex repeats in MIDI
+@cindex MIDI using repeats
+@funindex \unfoldRepeats
 
-In this example the volume of the clarinet is reduced relative to the
-volume of the flute.
+Repeats can be represented in the MIDI output by applying the
+@code{\unfoldRepeats} command.
 
-@lilypond[verbatim,quote]
-\score {
-  <<
-    \new Staff {
-      \key g \major
-      \time 2/2
-      \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
-      \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
-      }
-    }
-  >>
-  \layout {}
-  \midi {
-    \tempo 2 = 72
-  }
-}
-@end lilypond
+@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
+
+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
+\score @{
+  @var{@dots{} music @dots{}}
+  \layout @{ @}
+@}
+\score @{
+  \unfoldRepeats @{
+    @var{@dots{} music @dots{}}
+  @}
+  \midi @{ @}
+@}
+@end example
+
+When using multiple voices, each of the voices must contain completely
+unfolded repeats for correct MIDI output.
 
 @seealso
 Notation Reference:
-@ref{Score layout}.
+@ref{Repeats}.
+
+
+@node MIDI channel mapping
+@subsection MIDI channel mapping
+
+@cindex MIDI Channels
+@cindex MIDI Tracks
+@funindex midiChannelMapping
+
+When generating a MIDI file from a score, LilyPond will automatically
+assign every note in the score to a MIDI channel, the one on which it
+should be played when it is sent to a MIDI device.  A MIDI channel has
+a number of controls available to select, for example, the instrument
+to be used to play the notes on that channel, or to request the MIDI
+device to apply various effects to the sound produced on the channel.
+At all times, every control on a MIDI channel can have only a single
+value assigned to it (which can be modified, however, for example,
+to switch to another instrument in the middle of a score).
+
+The MIDI standard supports only 16 channels per MIDI device.  This
+limit on the number of channels also limits the number of different
+instruments which can be played at the same time.
+
+LilyPond creates separate MIDI tracks for each staff, (or discrete
+instrument or voice, depending on the value of
+@code{Score.midiChannelMapping}), and also for each lyrics context.
+There is no limit to the number of tracks.
+
+To work around the limited number of MIDI channels, LilyPond supports
+a number of different modes for MIDI channel allocation, selected using
+the @code{Score.midiChannelMapping} context property.  In each case,
+if more MIDI channels than the limit are required, the allocated
+channel numbers wrap around back to 0, possibly causing the incorrect
+assignment of instruments to some notes.  This context property can be
+set to one of the following values:
 
+@table @var
 
-@node Equalizing different instruments (ii)
-@unnumberedsubsubsec Equalizing different instruments (ii)
+@item @code{'staff}
 
-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}.
+Allocate a separate MIDI channel to each staff in the score (this is
+the default).  All notes in all voices contained within each staff will
+share the MIDI channel of their enclosing staff, and all are encoded
+in the same MIDI track.
 
-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 limit of 16 channels is applied to the total number of staff and
+lyrics contexts, even though MIDI lyrics do not take up a MIDI channel.
 
-The following example sets the relative flute and clarinet volumes to
-the same values as the previous example.
+@item @code{'instrument}
 
-@lilypond[verbatim,quote]
-#(define my-instrument-equalizer-alist '())
+Allocate a separate MIDI channel to each distinct MIDI instrument
+specified in the score.  This means that all the notes played with the
+same MIDI instrument will share the same MIDI channel (and track), even
+if the notes come from different voices or staves.
 
-#(set! my-instrument-equalizer-alist
-  (append
-    '(
-      ("flute" . (0.7 . 0.9))
-      ("clarinet" . (0.3 . 0.6)))
-    my-instrument-equalizer-alist))
+In this case the lyrics contexts do not count towards the MIDI channel
+limit of 16 (as they will not be assigned to a MIDI instrument), so
+this setting may allow a better allocation of MIDI channels when the
+number of staves and lyrics contexts in a score exceeds 16.
 
-#(define (my-instrument-equalizer s)
-  (let ((entry (assoc s my-instrument-equalizer-alist)))
-    (if entry
-      (cdr entry))))
+@item @code{'voice}
 
-\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
+Allocate a separate MIDI channel to each voice in the score that has a
+unique name among the voices in its enclosing staff.  Voices in
+different staves are always assigned separate MIDI channels, but any two
+voices contained within the same staff will share the same MIDI channel
+if they have the same name.  Because @code{midiInstrument} and the
+several MIDI controls for effects are properties of the staff context,
+they cannot be set separately for each voice.  The first voice will be
+played with the instrument and effects specified for the staff, and
+voices with a different name from the first will be assigned the default
+instrument and effects.
 
-@seealso
-Installed Files:
-@file{scm/midi.scm}.
+Note: different instruments and/or effects can be assigned to several
+voices on the same staff by moving the @code{Staff_performer} from the
+@code{Staff} to the @code{Voice} context, and leaving
+@code{midiChannelMapping} to default to @code{'staff} or set to
+@code{'instrument}; see the snippet below.
 
-Internals Reference:
-@rinternals{Dynamic_performer}.
+@end table
 
-@ignore
-@c Delete when satisfied this is adequately covered elsewhere -td
+For example, the default MIDI channel mapping of a score can be changed
+to the @code{'instrument} setting as shown:
 
-@n ode Microtones in MIDI
-@s ubsection Microtones in MIDI
+@example
+\score @{
+  ...music...
+  \midi @{
+    \context @{
+      \Score
+      midiChannelMapping = #'instrument
+    @}
+  @}
+@}
+@end example
 
-@cindex microtones in MIDI
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
 
-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 Context properties for MIDI effects
+@subsection Context properties for MIDI effects
+
+@cindex Effects in MIDI
+@cindex Pan position in MIDI
+@cindex Stereo balance in MIDI
+@cindex Balance in MIDI
+@cindex Expression in MIDI
+@cindex Reverb in MIDI
+@cindex Chorus level in MIDI
+@funindex midiPanPosition
+@funindex midiBalance
+@funindex midiExpression
+@funindex midiReverbLevel
+@funindex midiChorusLevel
+
+The following context properties can be used to apply various MIDI
+effects to notes played on the MIDI channel associated with the
+current staff, MIDI instrument or voice (depending on the value of the
+@code{Score.midiChannelMapping} context property and the context in
+which the @code{Staff_performer} is located; see
+@ref{MIDI channel mapping}).
+
+Changing these context properties will affect all notes played on the
+channel after the change, however some of the effects may even apply
+also to notes which are already playing (depending on the
+implementation of the MIDI output device).
+
+The following context properties are supported:
 
+@table @var
 
-@node Percussion in MIDI
-@subsection Percussion in MIDI
+@item @code{Staff.midiPanPosition}
 
-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.
+The pan position controls how the sound on a MIDI channel is
+distributed between left and right stereo outputs.  The context
+property accepts a number between -1.0 (@code{#LEFT}) and 1.0
+(@code{#RIGHT}); the value -1.0 will put all sound power to the left
+stereo output (keeping the right output silent), the value 0.0
+(@code{#CENTER}) will distribute the sound evenly between the left and
+right stereo outputs, and the value 1.0 will move all sound to the
+right stereo output.  Values between -1.0 and 1.0 can be used to obtain
+mixed distributions between left and right stereo outputs.
 
-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.
+@item @code{Staff.midiBalance}
 
-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.
+The stereo balance of a MIDI channel.  Similarly to the pan position,
+this context property accepts a number between -1.0 (@code{#LEFT}) and
+1.0 (@code{#RIGHT}).  It varies the relative volume sent to the two
+stereo speakers without affecting the distribution of the stereo
+signals.
 
-@c TODO Expand with examples, and any other issues
+@item @code{Staff.midiExpression}
 
-@seealso
-Notation Reference:
-@ref{Percussion},
-@ref{Score layout}.
+Expression level (as a fraction of the maximum available level) to
+apply to a MIDI channel.  A MIDI device combines the MIDI channel's
+expression level with a voice's current dynamic level (controlled using
+constructs such as @code{\p} or @code{\ff}) to obtain the total volume
+of each note within the voice.  The expression control could be used, for
+example, to implement crescendo or decrescendo effects over single
+sustained notes (not supported automatically by LilyPond).
+
+@c Issue 4059 contains an attached snippet which shows how this might
+@c be done, but this is too large and complex for the NR, even as a
+@c referenced snippet.  It could be added to the LSR.
+
+The expression level ranges from 0.0 (no expression, meaning zero
+volume) to 1.0 (full expression).
+
+@item @code{Staff.midiReverbLevel}
+
+Reverb level (as a fraction of the maximum available level) to apply
+to a MIDI channel.  This property accepts numbers between 0.0 (no
+reverb) and 1.0 (full effect).
+
+@item @code{Staff.midiChorusLevel}
+
+Chorus level (as a fraction of the maximum available level) to apply to
+a MIDI channel.  This property accepts numbers between 0.0 (no chorus
+effect) and 1.0 (full effect).
+
+@end table
 
-Internals Reference:
-@rinternals{Dynamic_performer}.
 
 @knownissues
-Because the general MIDI standard does not contain rim shots, the
-sidestick is used for this purpose instead.
 
+As MIDI files do not contain any actual audio data, changes in these
+context properties translate only to requests for changing MIDI channel
+controls in the outputted MIDI files.  Whether a particular MIDI device
+(such as a software MIDI player) can actually handle any of these
+requests in a MIDI file is entirely up to the implementation of the
+device: a device may choose to ignore some or all of these requests.
+Also, how a MIDI device will interpret different values for these
+controls (generally, the MIDI standard fixes the behavior only at the
+endpoints of the value range available for each control), and whether a
+change in the value of a control will affect notes already playing on
+that MIDI channel or not, is also specific to the MIDI device
+implementation.
+
+When generating MIDI files, LilyPond will simply transform the
+fractional values within each range linearly into values in a
+corresponding (7-bit, or 14-bit for MIDI channel controls which support
+fine resolution) integer range (0-127 or 0-32767, respectively),
+rounding fractional values towards the nearest integer away from zero.
+The converted integer values are stored as-is in the generated MIDI
+file.  Please consult the documentation of your MIDI device for
+information about how the device interprets these values.
+
+
+@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
-@subsection The Articulate script
 
-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.
+@node The articulate script
+@unnumberedsubsubsec The @file{articulate} script
 
-To use the Articulate script, you have to include it at the top of your
-input file,
+To use the @file{articulate} script add the appropriate @code{\include}
+command at the top of the input file;
 
 @example
 \include "articulate.ly"
 @end example
 
-and in the @code{\score} section do
+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.
 
 @example
-\unfoldRepeats \articulate <<
-  all the rest of the score@dots{}
->>
+\score @{
+  \articulate <<
+    @var{@dots{} music @dots{}}
+  >>
+  \midi @{ @}
+@}
 @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.
-
-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}.
+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 allow 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
+compensate for the note-shortening behavior.}
 
-@knownissues
-Articulate shortens chords and some music (esp. organ music) could
-sound worse.
 
 
 @node Extracting musical information
@@ -3366,7 +3617,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
@@ -3379,17 +3630,18 @@ lilypond file.ly >display.txt
 @end example
 
 @funindex \void
-Note that Lilypond does not just display the music expression, but
+Note that LilyPond does not just display the music expression, but
 also interprets it (since @code{\displayLilyMusic} returns it in
-addition to displaying it).  This is convenient since you can just
-insert @code{\displayLilyMusic} into existing music in order to get
-information about it.  If you don't actually want Lilypond to
-interpret the displayed music as well as display it, use @code{\void}
-in order to have it ignored:
+addition to displaying it).  Just insert @code{\displayLilyMusic} into
+the existing music in order to get information about it.
+
+To interpret and display a music section in the console but, at the same
+time, remove it from the output file use the @code{\void} command.
 
 @example
 @{
   \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+  c1
 @}
 @end example