]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/input.itely
Fixes black bars in NR
[lilypond.git] / Documentation / notation / input.itely
index 169ac357c7ba83807695095eecfdae20f482bb75..fe0af3b5daf4aaddcf320def4da0602a2dfaaea9 100644 (file)
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.15.39"
 
 @node General input and output
 @chapter General input and output
@@ -353,9 +353,11 @@ toplevel expression is one of the following:
 @item
 An output definition, such as @code{\paper}, @code{\midi}, and
 @code{\layout}.  Such a definition at the toplevel changes the default
-book-wide settings.  If more than one such definition of
-the same type is entered at the top level any definitions in the later
-expressions have precedence.
+book-wide settings.  If more than one such definition of the same type
+is entered at the top level the definitions are combined, but in
+conflicting situations the later definitions take precedence.  For
+details of how this affects the @code{\layout} block see
+@ref{The \layout block}.
 
 @item
 A direct scheme expression, such as
@@ -413,9 +415,10 @@ music expression will be translated into
         @{ c'4 d' e'2 @}
       @}
     @}
+    \layout @{ @}
   @}
-       \layout @{ @}
-       \header @{ @}
+  \paper @{ @}
+  \header @{ @}
 @}
 @end example
 
@@ -493,7 +496,7 @@ circumstances to avoid errors:
 @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{#} sign.
+expression, i.e. every item that begins with a @code{#}@tie{}sign.
 @item To separate all elements of a Scheme expression.
 @item In @code{lyricmode} to separate all the terms in both
 @code{\override} and @code{\set} commands.  In particular, spaces
@@ -503,11 +506,13 @@ after the entire command.
 
 @end itemize
 
-
 @seealso
 Learning Manual:
 @rlearning{How LilyPond input files work}.
 
+Notation Reference:
+@ref{The \layout block}.
+
 
 @node Titles and headers
 @section Titles and headers
@@ -518,6 +523,7 @@ some pieces include a lot more information.
 @menu
 * Creating titles headers and footers::
 * Custom headers footers and titles::
+* Creating footnotes::
 * Reference to page numbers::
 * Table of contents::
 @end menu
@@ -709,6 +715,7 @@ Notation Reference:
 Installed Files:
 @file{ly/titling-init.ly}.
 
+
 @node Default layout of headers and footers
 @unnumberedsubsubsec Default layout of headers and footers
 
@@ -979,6 +986,49 @@ variables:
 @item @code{evenFooterMarkup}
 @end itemize
 
+@cindex markup, conditional
+@cindex on-the-fly
+@funindex \on-the-fly
+
+The @code{\markup} command @code{\on-the-fly} can be used to add
+markup conditionally to header and footer text defined within the
+@code{\paper} block, using the following syntax:
+
+@example
+@code{variable} = @code{\markup} @{
+  ...
+  @code{\on-the-fly}  #@var{procedure}  @var{markup}
+  ...
+@}
+@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
+@var{markup} argument if and only if the condition is true.
+
+A number of ready-made procedures for testing various conditions are
+provided:
+
+@quotation
+@multitable {print-page-number-check-first-----} {should this page be printed-----}
+
+@headitem  Procedure name           @tab  Condition tested
+
+@item print-page-number-check-first @tab  should this page number be printed?
+@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 (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 part-last-page                @tab  last page in the book part?
+@item not-single-page               @tab  pages in book part > 1?
+
+@end multitable
+@end quotation
+
 The following example centers page numbers at the bottom of every
 page.  First, the default settings for @code{oddHeaderMarkup} and
 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
@@ -1007,11 +1057,296 @@ same layout by defining it as @code{\oddFooterMarkup}:
 }
 @end lilypond
 
+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}
+  @code{@{ \markup ... \fromproperty #'header: ... @}}
+@end example
+
+determines if the output is a single page.
+
 @seealso
 Notation Reference:
 @ref{Title blocks explained},
 @ref{Default layout of book and score title blocks}.
 
+Installed Files:
+@file{../ly/titling-init.ly}.
+
+
+@node Creating footnotes
+@subsection Creating footnotes
+
+There are two types of footnotes that can be created; automatic
+footnotes and manual footnotes.
+
+@menu
+* Footnotes overview::
+* Automatic footnotes::
+* Manual footnotes::
+@end menu
+
+@node Footnotes overview
+@unnumberedsubsubsec Footnotes overview
+
+Automatic footnotes create incrementing numerical indicators and manual
+footnotes allow a custom indicator to be created instead.  Footnotes are
+normally applied like @code{\tweak} and consequently can be placed
+directly on grobs (graphical objects) created by most music elements and
+post-events.  In cases where this does not work (like with bar lines and
+meter changes, where the grobs are produced as a consequence of property
+changes), footnotes can also be specified as a standalone music event
+affecting all grobs of a given type at a particular time step.
+
+The full form of a footnote command is
+
+@example
+\footnote @var{mark} @var{offset} @var{grob-name} @var{footnote}
+@var{music}
+@end example
+
+The elements are as follows:
+
+@table @var
+@item mark
+is a markup or string specifying the footnote mark which is used for
+both marking the reference point as well as the footnote itself at the
+bottom of the page.  It can be omitted (or equivalently replaced with
+@code{\default}) in which case a number in sequence will be generated.
+@item offset
+is a number pair such as @samp{#(2 . 1)} specifying the X and Y offset
+from the reference point where the mark will be placed.
+@item grob-name
+specifies a type of grob to mark (like @samp{#'Flag}).  If it is given,
+the respective grob will be used as a reference point even in case that
+its @q{cause} is not the referenced @var{music} itself but a grob
+created from it.  It can be omitted (or replaced with @code{\default}),
+and then only a directly created grob will be annotated.
+@item footnote
+This markup or string specifies the footnote text to use at the bottom
+of the page.
+@item music
+This is the item, a music event or chord constituent or post-event, that
+is being annotated.  While it cannot be omitted, it @emph{can} be
+replaced by @code{\default} in which case the footnote is not attached
+to a music expression in particular, but rather to a moment of time.  It
+is mandatory in this case to use the @var{grob-name} argument for
+selecting an affected grob type, like @samp{#'TimeSignature}.
+@end table
+
+Like with @code{\tweak}, if your @code{\footnote} is applied to a
+post-event or articulation, it will itself have to be preceded with
+@code{-} to make the parser attach the result to the preceding note or
+rest.
+
+@node Automatic footnotes
+@unnumberedsubsubsec Automatic footnotes
+
+Automatic footnotes take four arguments: the @samp{(x . y)} position of
+the indicator, the optional @var{grob-name} specifying the layout object
+to be annotated, the @var{footnote} markup itself that will appear at
+the bottom of the page, and of course the @var{music} to attach the
+footnote to.
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { tagline = ##f }
+  \relative c' {
+    \footnote #'(0.5 . -2)
+      \markup { The first note }
+    a'4 b8
+    \footnote #'(0.5 . 1) #'Flag
+      \markup { The third note }
+    e\noBeam c4 d4
+  }
+}
+@end lilypond
+
+Chorded notes pose no particular difficulty:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { tagline = ##f }
+  \relative c' {
+    <
+    \footnote #'(1 . -1.25) "Here is a C" c
+    \footnote #'(2 . -0.25) \markup { \italic "An E-flat" } es
+    \footnote #'(2 . 3) \markup { \bold "This is a G" } g
+    >1
+  }
+}
+@end lilypond
+
+@warning {When footnotes have the same vertical position, the footnotes
+are printed in order of descendancy; the higher the footnote, the
+higher up in the list.}
+
+Here are some more examples of footnoted grobs, also showing the
+relative position of the footnotes to the tagline and copyright.
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { copyright = \markup { "Copyright 1970" } }
+  \relative c' {
+    a'4-\footnote #'(-3 . 0) \markup { \bold Forte } \f
+    -\footnote #'(0 . 1.5) \markup { A slur } (
+    b8)-\footnote #'(0 . -2) \markup { Beam } [ e]
+    \footnote #'(1 . -1) #'Stem
+      \markup  { \teeny { This is a stem } }
+    c4
+    \footnote #'(0 . 0.5) #'AccidentalCautionary
+      \markup \italic { A cautionary accidental }
+    \footnote #'(1 . 1) "The note itself"
+    dis?4-\footnote #'(0.5 . -0.5) \markup \italic { Slow Down }
+         _"rit."
+  }
+}
+@end lilypond
+
+For top-level @code{\markup}, the @code{\auto-footnote} command is
+required:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { tagline = ##f }
+  \markup { \auto-footnote "A simple tune" \italic "By me" }
+  \relative c' {
+    a'4 b8 e c4 d
+  }
+}
+@end lilypond
+
+
+@node Manual footnotes
+@unnumberedsubsubsec Manual footnotes
+
+@cindex footnotes, manual
+
+Manually marked footnotes take an additional first markup argument
+@var{mark} for making the reference mark.  In contrast to automatically
+generated footnote marks, they will not appear before the @var{footnote}
+markup at the bottom of the page: establishing the visual connection is
+left to the user.  LilyPond will only make sure that the corresponding
+markup appears on the bottom of the same page.
+
+Other than that, the use is identical to that of automatically numbered
+footnotes.
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { tagline = ##f }
+  \relative c' {
+    \footnote
+          "1" #'(0.5 . -2)
+          \markup { \italic "1. The first note" }
+    a'4
+    b8
+    \footnote
+          \markup { \bold "2" } #'(0.5 . 1)
+          "2. The second note"
+    e
+    c4
+    d-\footnote "3" #'(0.5 . -1) "3. Piano" \p
+  }
+}
+@end lilypond
+
+To annotate chorded notes with manual footnotes:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { tagline = ##f }
+  \relative c' {
+    <
+    \footnote "1" #'(1 . -1.25) "1. C" c
+    \footnote
+       \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" es
+    \footnote "3" #'(2 . 3) \markup { \italic "iii. G" } g
+    >1
+  }
+}
+@end lilypond
+
+@warning {When footnotes have the same vertical position, the footnotes
+are printed in order of descendancy; the higher the footnote, the
+higher up in the list.}
+
+Here are some examples of manually footnoted grobs, also showing
+the relative position of the footnotes to the tagline and copyright
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { tagline = ##f }
+  \relative c' {
+    a'4-\footnote
+      \markup { \teeny 1 } #'(-3 . 0)
+      \markup { 1. \bold Forte } \f
+    -\footnote
+      \markup { \teeny b } #'(0 . 1.5)
+      \markup { b. A slur } (
+    b8)-\footnote
+      \markup { \teeny 3 } #'(0 . -2)
+      \markup { 3. Beam } [
+    e]
+    \footnote
+      \markup { 4 } #'(1 . -1) #'Stem
+      \markup  { \bold 4. { This is a stem } }
+    c4
+    \footnote
+      \markup \concat \teeny { "sharp (v)" }
+          #'(0 . 0.5) #'AccidentalCautionary
+      \markup \italic { v. A cautionary accidental }
+    dis?4-\footnote
+      \markup \concat \teeny { "a" } #'(0.5 . -0.5)
+      \markup \italic { a. Slow Down } _"rit."
+    \footnote
+      \markup { \teeny \musicglyph #"rests.4" }
+          #'(1.5 . -0.25)
+      \markup { \null } \breathe
+  }
+}
+@end lilypond
+
+To manually footnote a top-level @code{\markup}:
+
+@lilypond[verbatim,quote,ragged-right,papersize=a8]
+\book {
+  \header { tagline = ##f }
+  \markup { "A simple tune" \footnote "*" \italic "* By me" }
+  \relative c' {
+    a'4 b8 e c4 d4
+  }
+}
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{Objects and interfaces}.
+
+Notation Reference:
+@ref{Balloon help},
+@ref{Page layout},
+@ref{Text marks},
+@ref{Text scripts},
+@ref{Titles and headers}.
+
+Internals Reference:
+@rinternals{FootnoteEvent},
+@rinternals{FootnoteItem},
+@rinternals{FootnoteSpanner},
+@rinternals{Footnote_engraver}.
+
+@knownissues
+Multiple footnotes for the same page can only be stacked, one on top of
+the other, and cannot be printed on the same line.  Footnotes cannot be
+attached to @code{MultiMeasureRests} and may collide with @code{Staff},
+@code{\markup} objects and other @code{footnote} annotations.  When
+using any manual @code{footnote} command a @code{\paper} block
+containing @code{footnote-auto-number = ##f} is required.
+
 
 @node Reference to page numbers
 @subsection Reference to page numbers
@@ -1021,7 +1356,7 @@ command, either at top-level or inside music.  This label can then be
 referred to in a markup, to get the number of the page where the marked
 point is placed, using the @code{\page-ref} markup command.
 
-@lilypond[verbatim]
+@lilypond[verbatim,papersize=a8landscape]
 \header { tagline = ##f }
 \book {
   \label #'firstScore
@@ -1065,13 +1400,13 @@ ie. a two digit number.
 
 @node Table of contents
 @subsection Table of contents
-A table of contents is included using the @code{\markuplines \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.
 
 @verbatim
-\markuplines \table-of-contents
+\markuplist \table-of-contents
 \pageBreak
 
 \tocItem \markup "First score"
@@ -1139,7 +1474,7 @@ tocAct =
    (add-toc-item! 'tocActMarkup text))
 @end verbatim
 
-@lilypond[line-width=11.0\cm]
+@lilypond[line-width=10.0\cm]
 \header { tagline = ##f }
 \paper {
   tocActMarkup = \markup \large \column {
@@ -1154,7 +1489,7 @@ tocAct =
    (add-toc-item! 'tocActMarkup text))
 
 \book {
-  \markuplines \table-of-contents
+  \markuplist \table-of-contents
   \tocAct \markup { Atto Primo }
   \tocItem \markup { Coro. Viva il nostro Alcide }
   \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
@@ -1167,24 +1502,23 @@ tocAct =
 
 Dots can be added to fill the line between an item and its page number:
 
-@lilypond[verbatim,quote]
+@lilypond[verbatim,line-width=10.0\cm]
 \header { tagline = ##f }
 \paper {
   tocItemMarkup = \tocItemWithDotsMarkup
 }
 
 \book {
-  \markuplines \table-of-contents
+  \markuplist \table-of-contents
   \tocItem \markup { Allegro }
   \tocItem \markup { Largo }
   \markup \null
 }
 @end lilypond
 
-
 @seealso
-Init files: @file{../ly/toc-init.ly}.
-
+Installed Files:
+@file{ly/toc-init.ly}.
 
 @predefined
 @funindex \table-of-contents
@@ -1200,7 +1534,7 @@ Init files: @file{../ly/toc-init.ly}.
 @menu
 * Including LilyPond files::
 * Different editions from one source::
-* Text encoding::
+* Special characters::
 @end menu
 
 
@@ -1258,7 +1592,7 @@ been brought into the main file, so the file names they specify
 must all be relative to the directory containing the main file,
 not the directory containing the included file.  However,
 this behavior can be changed by passing the option
-@code{-drelative-includes} option at the command line
+@option{-drelative-includes} option at the command line
 (or by adding @code{#(ly:set-option 'relative-includes #t)}
 at the top of the main input file).  With @code{relative-includes}
 set, the path for each @code{\include} command will be taken
@@ -1306,32 +1640,30 @@ version of LilyPond.
 Some simple examples of using @code{\include} are shown in
 @rlearning{Scores and parts}.
 
-
 @seealso
 Learning Manual:
 @rlearning{Other sources of information},
 @rlearning{Scores and parts}.
 
-
 @knownissues
-
 If an included file is given a name which is the same as one in
 LilyPond's installation files, LilyPond's file from the
 installation files takes precedence.
 
 
-
 @node Different editions from one source
 @subsection Different editions from one source
 
-Several mechanisms are available to facilitate the generation
-of different versions of a score from the same music source.
-Variables are perhaps most useful for combining lengthy sections
-of music and/or annotation in various ways, while tags are more
-useful for selecting one from several alternative shorter sections
-of music.  Whichever method is used, separating the notation from
-the structure of the score will make it easier to change the
-structure while leaving the notation untouched.
+Several methods can be used to generate different versions of a score
+from the same music source.  Variables are perhaps the most useful for
+combining lengthy sections of music and/or annotation.  Tags are more
+useful for selecting one section from several alternative shorter
+sections of music, and can also be used for splicing pieces of music
+together at different points.
+
+Whichever method is used, separating the notation from the structure of
+the score will make it easier to change the structure while leaving the
+notation untouched.
 
 @menu
 * Using variables::
@@ -1406,9 +1738,12 @@ 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}.
@@ -1533,6 +1868,30 @@ 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.
 
+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
+@code{elements} of an existing music construct.  Not every music
+construct has @code{elements}, but sequential and simultaneous music are
+safe bets:
+
+@lilypond[verbatim,quote]
+test = { \tag #'here { \tag #'here <<c''>> } }
+
+{
+  \pushToTag #'here c'
+  \pushToTag #'here e'
+  \pushToTag #'here g' \test
+  \appendToTag #'here c'
+  \appendToTag #'here e'
+  \appendToTag #'here g' \test
+}
+@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.
 
 @seealso
 Learning Manual:
@@ -1542,19 +1901,18 @@ Notation Reference:
 @ref{Automatic part combining},
 @ref{Including LilyPond files}.
 
-
 @ignore
 @c This warning is more general than this placement implies.
 @c Rests are not merged whether or not they come from tagged sections.
 @c Should be deleted?  -td
 
 @knownissues
-
 Multiple rests are not merged if you create a score with more
 than one tagged section at the same place.
 
 @end ignore
 
+
 @node Using global settings
 @unnumberedsubsubsec Using global settings
 
@@ -1582,12 +1940,24 @@ Learning Manual:
 Notation Reference:
 @ref{Including LilyPond files}.
 
+
+@node Special characters
+@subsection Special characters
+
+@cindex special characters
+@cindex non-ASCII characters
+
+@menu
+* Text encoding::
+* Unicode::
+* ASCII aliases::
+@end menu
+
+
 @node Text encoding
-@subsection Text encoding
+@unnumberedsubsubsec Text encoding
 
-@cindex Unicode
 @cindex UTF-8
-@cindex non-ASCII characters
 
 LilyPond uses the character repertoire defined by the Unicode
 consortium and ISO/IEC 10646.  This defines a unique name and
@@ -1652,6 +2022,12 @@ portuguese = \lyricmode {
 \addlyrics { \portuguese }
 @end lilypond
 
+
+@node Unicode
+@unnumberedsubsubsec Unicode
+
+@cindex Unicode
+
 To enter a single character for which the Unicode code point is
 known but which is not available in the editor being used, use
 either @code{\char ##xhhhh} or @code{\char #dddd} within a
@@ -1687,7 +2063,7 @@ lyrics and as stand-alone text below the score:
   }
   \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
 }
-\markup { "Copyright 2008--2011" \char ##x00A9 }
+\markup { "Copyright 2008--2012" \char ##x00A9 }
 @end lilypond
 
 @cindex copyright sign
@@ -1701,6 +2077,57 @@ To enter the copyright sign in the copyright notice use:
 @end example
 
 
+@node ASCII aliases
+@unnumberedsubsubsec ASCII aliases
+
+A list of ASCII aliases for special characters can be included:
+
+@lilypond[quote,verbatim]
+\paper {
+  #(include-special-characters)
+}
+
+\markup "&flqq; &ndash; &OE;uvre incomplète&hellip; &frqq;"
+
+\score {
+  \new Staff { \repeat unfold 9 a'4 }
+  \addlyrics {
+    This is al -- so wor -- kin'~in ly -- rics: &ndash;_&OE;&hellip;
+  }
+}
+
+\markup \column {
+  "The replacement can be disabled:"
+  "&ndash; &OE; &hellip;"
+  \override #'(replacement-alist . ()) "&ndash; &OE; &hellip;"
+}
+@end lilypond
+
+You can also make your own aliases, either globally:
+
+@lilypond[quote,verbatim]
+\paper {
+  #(add-text-replacements!
+    '(("100" . "hundred")
+      ("dpi" . "dots per inch")))
+}
+\markup "A 100 dpi."
+@end lilypond
+
+or locally:
+
+@lilypond[quote,verbatim]
+\markup \replace #'(("100" . "hundred")
+                    ("dpi" . "dots per inch")) "A 100 dpi."
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{List of special characters}.
+
+Installed Files:
+@file{ly/text-replacements.ly}.
+
 
 @node Controlling output
 @section Controlling output
@@ -1742,7 +2169,7 @@ More clip regions can be defined by adding more pairs of
 rhythmic-locations to the list.
 
 In order to use this feature, LilyPond must be invoked with
-@code{-dclip-systems}.  The clips are output as EPS files, and are
+@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}.
@@ -1805,8 +2232,8 @@ 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{Command line options for
-lilypond}.
+command line options, see
+@rprogram{Basic command line options for LilyPond}.
 
 
 @node Replacing the notation font
@@ -1838,7 +2265,8 @@ existing @code{fonts} directory to @code{fonts_orig} and the
 reverse the process.
 
 @seealso
-Learning Manual: @rlearning{Other sources of information}.
+Learning Manual:
+@rlearning{Other sources of information}.
 
 @knownissues
 Gonville cannot be used to typeset @q{Ancient Music} notation and it is
@@ -1865,14 +2293,13 @@ 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 oputput is somewhat crude; optionally, an enhanced and
+Standard MIDI output is somewhat crude; optionally, an enhanced and
 more realistic MIDI output is available by means of
 @ref{The Articulate script}.
 
-@c TODO Check this
-The midi output allocates a channel for each staff, and one for global
-settings.  Therefore the midi file should not have more than 15 staves
-(or 14 if you do not use drums).  Other staves will remain silent.
+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.
 
 @menu
 * Creating MIDI files::
@@ -1975,7 +2402,7 @@ instrument is used.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {changing-midi-output-to-one-channel-per-voice.ly}
 
 @knownissues
@@ -2025,24 +2452,16 @@ indication to be printed:
 \score @{
   @var{...music...}
   \midi @{
-    \context @{
-      \Score
-      tempoWholesPerMinute = #(ly:make-moment 72 4)
-    @}
+    \tempo 4 = 72
   @}
 @}
 @end example
 
 In this example the tempo is set to 72 quarter note
-beats per minute.  This kind of tempo specification cannot take
-a dotted note length as an argument.  If one is required, break
-the dotted note into smaller units.  For example, a tempo of 90
-dotted quarter notes per minute can be specified as 270 eighth
-notes per minute:
-
-@example
-tempoWholesPerMinute = #(ly:make-moment 270 8)
-@end example
+beats per minute.  @code{\tempo} is actually a music command for
+setting properties during the interpretation of music: in the
+context of output definitions like a @code{\midi} block, as a matter of
+courtesy those are reinterpreted as if they were context modifications.
 
 @cindex MIDI context definitions
 
@@ -2289,9 +2708,9 @@ volume is limited to the range 0.2 - 0.5.
   >>
   \layout {}
   \midi {
+    \tempo 2 = 72
     \context {
       \Score
-      tempoWholesPerMinute = #(ly:make-moment 72 2)
       midiMinimumVolume = #0.2
       midiMaximumVolume = #0.5
     }
@@ -2341,10 +2760,7 @@ correctly.
   >>
   \layout {}
   \midi {
-    \context {
-      \Score
-      tempoWholesPerMinute = #(ly:make-moment 72 2)
-    }
+    \tempo 2 = 72
   }
 }
 @end lilypond
@@ -2410,10 +2826,7 @@ to the same values as the previous example.
   >>
   \layout { }
   \midi {
-    \context {
-      \Score
-      tempoWholesPerMinute = #(ly:make-moment 72 2)
-    }
+    \tempo 2 = 72
   }
 }
 @end lilypond
@@ -2535,8 +2948,9 @@ display musical information as text.
 
 @funindex \displayLilyMusic
 Displaying a music expression in LilyPond notation can be
-done with the music function @code{\displayLilyMusic} but only when
-using the command line.  For example,
+done with the music function @code{\displayLilyMusic}.  To see the
+output, you will typically want to call LilyPond using the command
+line.  For example,
 
 @example
 @{
@@ -2559,6 +2973,21 @@ redirect the output to a file.
 lilypond file.ly >display.txt
 @end example
 
+@funindex \void
+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:
+
+@example
+@{
+  \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
 
 @node Displaying scheme music expressions
 @subsection Displaying scheme music expressions