X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finput.itely;h=392fbb3ea00f7094959440fdf70b8cefaefbffdb;hb=5c14a087ca6cbd665fd631452b7b1283ba0387c3;hp=ffd64f48679277cfff6cf40ae0c16d63a0c81bf5;hpb=edf17353d89f4f6bd831466262402bb9151a26ca;p=lilypond.git

diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely
index ffd64f4867..392fbb3ea0 100644
--- a/Documentation/user/input.itely
+++ b/Documentation/user/input.itely
@@ -7,20 +7,20 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.11.61"
 
-@node Input syntax
-@chapter Input syntax
+@node General input and output
+@chapter General input and output
 
-This section deals with general LilyPond input syntax issues,
+This section deals with general LilyPond input and output issues,
 rather than specific notation.
 
 @menu
-* Input structure::
-* Titles and headers::
-* Working with input files::
-* Controlling output::
-* MIDI output::
+* Input structure::             
+* Titles and headers::          
+* Working with input files::    
+* Controlling output::          
+* MIDI output::                 
 @end menu
 
 
@@ -31,9 +31,9 @@ The main format of input for LilyPond are text files.  By convention,
 these files end with @code{.ly}.
 
 @menu
-* Structure of a score::
-* Multiple scores in a book::
-* File structure::
+* Structure of a score::        
+* Multiple scores in a book::   
+* File structure::              
 @end menu
 
 
@@ -221,7 +221,7 @@ A @code{\score} block.  This score will be collected with other
 toplevel scores, and combined as a single @code{\book}.
 This behavior can be changed by setting the variable
 @code{toplevel-score-handler} at toplevel.  The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
+defined in the init file @file{../scm/@/lily@/.scm}.
 
 @item
 A @code{\book} block logically combines multiple movements
@@ -236,7 +236,7 @@ a @code{\book} block if you want more than a single @code{\score}
 or @code{\markup} in the same example.  This behavior can be
 changed by setting the variable @code{toplevel-book-handler} at
 toplevel.  The default handler is defined in the init file
-@file{scm/@/lily@/.scm}.
+@file{../scm/@/lily@/.scm}.
 
 @item
 A compound music expression, such as
@@ -265,7 +265,7 @@ music expression will be translated into
 
 This behavior can be changed by setting the variable
 @code{toplevel-music-handler} at toplevel.  The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
+defined in the init file @file{../scm/@/lily@/.scm}.
 
 @item
 A markup text, a verse for example
@@ -287,7 +287,7 @@ foo = @{ c4 d e d @}
 @end example
 
 This can be used later on in the file by entering @code{\foo}.  The
-name of an variable should have alphabetic characters only; no
+name of a variable should have alphabetic characters only; no
 numbers, underscores or dashes.
 
 @end itemize
@@ -337,10 +337,10 @@ Almost all printed music includes a title and the composer's name;
 some pieces include a lot more information.
 
 @menu
-* Creating titles::
-* Custom titles::
-* Reference to page numbers::
-* Table of contents::
+* Creating titles::             
+* Custom titles::               
+* Reference to page numbers::   
+* Table of contents::           
 @end menu
 
 
@@ -373,32 +373,32 @@ Subsubtitle, centered below the subtitle.
 
 @funindex poet
 @item poet
-Name of the poet, flush-left below the subtitle.
+Name of the poet, flush-left below the subsubtitle.
+
+@funindex instrument
+@item instrument
+Name of the instrument, centered below the subsubtitle.  Also
+centered at the top of pages (other than the first page).
 
 @funindex composer
 @item composer
-Name of the composer, flush-right below the subtitle.
+Name of the composer, flush-right below the subsubtitle.
 
 @funindex meter
 @item meter
 Meter string, flush-left below the poet.
 
-@funindex opus
-@item opus
-Name of the opus, flush-right below the composer.
-
 @funindex arranger
 @item arranger
-Name of the arranger, flush-right below the opus.
-
-@funindex instrument
-@item instrument
-Name of the instrument, centered below the arranger.  Also
-centered at the top of pages (other than the first page).
+Name of the arranger, flush-right below the composer.
 
 @funindex piece
 @item piece
-Name of the piece, flush-left below the instrument.
+Name of the piece, flush-left below the meter.
+
+@funindex opus
+@item opus
+Name of the opus, flush-right below the arranger.
 
 @cindex page breaks, forcing
 @funindex breakbefore
@@ -428,13 +428,13 @@ may use any @ref{Formatting text}, commands in the header.
 \book {
   \header {
     dedication = "dedicated to me"
-    title = \markup \center-align { "Title first line" "Title second line,
+    title = \markup \center-column { "Title first line" "Title second line,
 longer" }
     subtitle = "the subtitle,"
     subsubtitle = #(string-append "subsubtitle LilyPond version "
 (lilypond-version))
     poet = "Poet"
-    composer =  \markup \center-align { "composer" \small "(1847-1973)" }
+    composer =  \markup \center-column { "composer" \small "(1847-1973)" }
     texttranslator = "Text Translator"
     meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
 "r" }
@@ -498,14 +498,14 @@ Note that the music expression must come before the @code{\header}.
 }
 @end lilypond
 
-@funindex printallheaders
+@funindex print-all-headers
 @noindent
 You may change this behavior (and print all the headers when defining
 @code{\header} inside @code{\score}) by using
 
 @example
 \paper@{
-  printallheaders=##t
+  print-all-headers = ##t
 @}
 @end example
 
@@ -534,7 +534,7 @@ Headers may be completely removed by setting them to false.
 
 A more advanced option is to change the definitions of the following
 variables in the @code{\paper} block.  The init file
-@file{ly/titling-init.ly} lists the default layout.
+@file{../ly/titling-init.ly} lists the default layout.
 
 @table @code
 @funindex bookTitleMarkup
@@ -746,7 +746,7 @@ tocAct =
 
 @seealso
 
-Init files: @file{ly/@/toc@/-init@/.ly}.
+Init files: @file{../ly/@/toc@/-init@/.ly}.
 
 @predefined
 
@@ -760,10 +760,10 @@ Init files: @file{ly/@/toc@/-init@/.ly}.
 @section Working with input files
 
 @menu
-* Including LilyPond files::
-* Different editions from one source::
-* Text encoding::
-* Displaying LilyPond notation::
+* Including LilyPond files::    
+* Different editions from one source::  
+* Text encoding::               
+* Displaying LilyPond notation::  
 @end menu
 
 
@@ -885,8 +885,8 @@ the structure of the score will make it easier to change the
 structure while leaving the notation untouched.
 
 @menu
-* Using variables::
-* Using tags::
+* Using variables::             
+* Using tags::                  
 @end menu
 
 @node Using variables
@@ -1130,7 +1130,7 @@ Unicode-aware editor and saving the file with UTF-8 encoding.  Most
 popular modern editors have UTF-8 support, for example, vim, Emacs,
 jEdit, and GEdit do.  All MS Windows systems later than NT use
 Unicode as their native character encoding, so even Notepad can
-edit and save a file in UTF-8 format.  A more functional 
+edit and save a file in UTF-8 format.  A more functional
 alternative for Windows is BabelPad.
 
 If a LilyPond input file containing a non-ASCII character is not
@@ -1145,7 +1145,8 @@ will be generated.
 Here is an example showing Cyrillic, Hebrew and Portuguese
 text:
 
-@lilypond[verbatim,quote]
+@lilypond[quote]
+%c No verbatim here as the code does not display correctly in PDF
 % Cyrillic
 bulgarian = \lyricmode {
   Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
@@ -1170,22 +1171,38 @@ portuguese = \lyricmode {
 @end lilypond
 
 To enter a single character for which the Unicode escape sequence
-is known but which is not available in the editor being used, enter
-
-@example
-#(ly:export (ly:wide-char->utf-8 #x03BE))
-@end example
+is known but which is not available in the editor being used, use
+@code{\char ##xhhhh} within a @code{\markup} block, where
+@code{hhhh} is the hexadecimal code for the character required.
+For example, @code{\char ##x03BE} enters the Unicode U+03BE
+character, which has the Unicode name @qq{Greek Small Letter Xi}.
+Any Unicode hexadecimal code may be substituted, and if all special
+characters are entered in this format it is not necessary to save
+the input file in UTF-8 format.  Of course, a font containing all
+such encoded characters must be installed and available to LilyPond.
+
+The following example shows UTF-8 coded characters being used in
+four places -- in a rehearsal mark, as articulation text, in lyrics
+and as stand-alone text below the score:
 
-where in this example @code{x03BE} is the hexadecimal code for the
-Unicode U+03BE character, which has the Unicode name @qq{Greek Small
-Letter Xi}.  Any Unicode hexadecimal code may be substituted, and
-if all special characters are entered in this format it is not
-necessary to save the input file in UTF-8 format.
+@lilypond[quote,verbatim]
+\score {
+  \relative c'' {
+    c1 \mark \markup { \char ##x03EE }
+    c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
+  }
+  \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } }
+}
+\markup { "Copyright 2008" \char ##x00A9 }
+@end lilypond
 
-@knownissues
+To enter the copyright sign in the copyright notice use:
 
-The @code{ly:export} format may be used in text within @code{\mark} or
-@code{\markup} commands but not in lyrics.
+@example
+\header @{
+  copyright = \markup @{ \char ##x00A9 "2008" @}
+@}
+@end example
 
 @node Displaying LilyPond notation
 @subsection Displaying LilyPond notation
@@ -1223,8 +1240,8 @@ lilypond file.ly >display.txt
 @section Controlling output
 
 @menu
-* Extracting fragments of music::
-* Skipping corrected music::
+* Extracting fragments of music::  
+* Skipping corrected music::    
 @end menu
 
 @node Extracting fragments of music
@@ -1331,18 +1348,19 @@ settings.  Therefore the midi file should not have more than 15 staves
 (or 14 if you do not use drums).  Other staves will remain silent.
 
 @menu
-* Creating MIDI files::
-* MIDI block::
-* MIDI instrument names::
-* Repeats in MIDI::
-* What else goes into the MIDI output?::
+* Creating MIDI files::         
+* MIDI block::                  
+* What goes into the MIDI output?::  
+* Repeats in MIDI::             
+* Controlling MIDI dynamics::   
+* Percussion in MIDI::          
 @end menu
 
 @node Creating MIDI files
 @subsection Creating MIDI files
 
-To create a MIDI output file from a LilyPond input file, add a @code{\midi} block
-to a score, for example,
+To create a MIDI output file from a LilyPond input file, add a
+@code{\midi} block to a score, for example,
 
 @example
 \score @{
@@ -1380,23 +1398,37 @@ can be suppressed, see @ref{Metronome marks}.  An alternative way
 of specifying the inital or overall MIDI tempo is described below,
 see @ref{MIDI block}.
 
-@ignore
-@c TODO Investigate dynamicAbsoluteVolumeFunction and the two
-@c midi..Volume properties, then document properly.
+@unnumberedsubsubsec Instrument names
+
+@cindex instrument names
+@funindex Staff.midiInstrument
 
-The fractions can be adjusted by setting
-@code{dynamicAbsoluteVolumeFunction} in @rinternals{Voice} context.
-For each type of MIDI instrument, a volume range can be defined.  This
-gives a basic equalizer control, which can enhance the quality of
-the MIDI output remarkably.  The equalizer can be controlled by
-setting @code{instrumentEqualizer}, or by setting
+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
-\set Staff.midiMinimumVolume = #0.2
-\set Staff.midiMaximumVolume = #0.8
+\new Staff @{
+  \set Staff.midiInstrument = "glockenspiel"
+  @var{...notes...}
+@}
 @end example
 
-@end ignore
+@example
+\new Staff \with @{midiInstrument = "cello"@} @{
+  @var{...notes...}
+@}
+@end example
+
+If the selected instrument does not exactly match an instrument from
+the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
+instrument is used.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{changing-midi-output-to-one-channel-per-voice.ly}
 
 @knownissues
 
@@ -1429,7 +1461,6 @@ Not all midi players correctly handle tempo changes in the midi
 output.  Players that are known to work include MS Windows Media
 Player and @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
 
-
 @node MIDI block
 @subsection MIDI block
 @cindex MIDI block
@@ -1445,12 +1476,12 @@ indication to be printed:
 @example
 \score @{
   @var{...music...}
-   \midi @{
-     \context @{
-       \Score
-       tempoWholesPerMinute = #(ly:make-moment 72 4)
-       @}
-     @}
+  \midi @{
+    \context @{
+      \Score
+      tempoWholesPerMinute = #(ly:make-moment 72 4)
+    @}
+  @}
 @}
 @end example
 
@@ -1470,8 +1501,9 @@ tempoWholesPerMinute = #(ly:make-moment 270 8)
 Context definitions follow precisely the same syntax as those
 within a @code{\layout} block.  Translation modules for sound are
 called performers.  The contexts for MIDI output are defined in
-@file{ly/@/performer@/-init@/.ly} (see @rlearning{Other sources
-of information}.  For example, to remove the effect of dynamics
+@file{../ly/@/performer@/-init@/.ly},
+see @rlearning{Other sources of information}.
+For example, to remove the effect of dynamics
 from the MIDI output, insert the following lines in the
 @code{\midi@{ @}} block.
 
@@ -1499,30 +1531,56 @@ in a @code{\score} block.
 @}
 @end example
 
-@snippets
+@node What goes into the MIDI output?
+@subsection What goes into the MIDI output?
 
-@c TODO Check header and text appear in this example
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{changing-midi-output-to-one-channel-per-voice.ly}
+@c TODO Check grace notes - timing is suspect?
 
-@node MIDI instrument names
-@subsection MIDI instrument names
+@unnumberedsubsubsec Supported in MIDI
 
-@cindex instrument names
-@funindex Staff.midiInstrument
+@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
+@c TODO etc
 
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property.  The instrument name should be chosen from the list in
-@ref{MIDI instruments}.
+The following items of notation are reflected in the MIDI output:
 
-@example
-\set Staff.midiInstrument = "glockenspiel"
-@var{...notes...}
-@end example
+@itemize
+@item Pitches
+@item Quarter tones (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
+@end itemize
 
-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.
+@unnumberedsubsubsec Unsupported in MIDI
+
+@c TODO index as above
+
+The following items of notation have no effect on the MIDI output:
+
+@itemize
+@item Rhythms entered as annotations, e.g. swing
+@item Tempo changes entered as annotations with no tempo marking
+@item Staccato and other articulations and ornamentations
+@item Slurs and Phrasing slurs
+@item Crescendi, decrescendi over a single note
+@item Tremolos entered with @q{@code{:}[@var{number}]}
+@item Figured bass
+@end itemize
 
 
 @node Repeats in MIDI
@@ -1565,13 +1623,239 @@ and percent repeats).  For example,
 @}
 @end example
 
+@node Controlling MIDI dynamics
+@subsection Controlling MIDI dynamics
+
+MIDI dynamics are implemented by the Dynamic_performer which lives
+by default in the Voice context.  It is possible to control the
+overall MIDI volume, the relative volume of dynamic markings and
+the relative volume of different instruments.
+
+@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 rfz is
+found, or calls the default function otherwise.
 
-@node What else goes into the MIDI output?
-@subsection What else goes into the MIDI output?
+@lilypond[verbatim,quote]
+#(define (myDynamics dynamic)
+    (if (equal? dynamic "rfz")
+      0.9
+      (default-dynamic-absolute-volume dynamic)))
 
-@c TODO Check grace notes - timing is suspect?
+\score {
+  \new Staff {
+    \set Staff.midiInstrument = "cello"
+    \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
+    \new Voice {
+       \relative c'' {
+         a\pp b c-\rfz
+       }
+    }
+  }
+  \layout {}
+  \midi {}
+}
+@end lilypond
+
+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.
+
+@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 on dynamic marks, so if they
+are to apply from the start of the score a dynamic mark must be
+placed there.  The fraction corresponding to each dynamic mark is
+modified with this formula
+
+@example
+midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
+@end example
+
+In the following example the dynamic range of the overall MIDI
+volume is limited to the range 0.2 - 0.5.
+
+@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 ~
+        fis4 g8 fis e2 ~
+        e4 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 {
+    \context {
+      \Score
+      tempoWholesPerMinute = #(ly:make-moment 72 2)
+      midiMinimumVolume = #0.2
+      midiMaximumVolume = #0.5
+    }
+  }
+}
+@end lilypond
+
+@unnumberedsubsubsec Equalizing different instruments (i)
+
+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.
+
+In this example the volume of the clarinet is reduced relative
+to the volume of the flute.  There must be a dynamic
+mark on the first note of each instrument for this to work
+correctly.
+
+@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 ~
+        fis4 g8 fis e2 ~
+        e4 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 {
+    \context {
+      \Score
+      tempoWholesPerMinute = #(ly:make-moment 72 2)
+    }
+  }
+}
+@end lilypond
+
+@unnumberedsubsubsec Equalizing different instruments (ii)
+
+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}.
 
-@unnumberedsubsubsec Microtones
+This basic default equalizer can be replaced by setting
+@code{instrumentEqualizer} in the @code{Score} context to a new
+Scheme procedure which accepts a MIDI instrument name as its only
+argument and returns a pair of fractions giving the minimum and
+maximum volumes to be applied to that instrument.  This replacement
+is done in the same way as shown for resetting the
+@code{dynamicAbsoluteVolumeFunction} at the start of this section.
+The default equalizer, @notation{default-instrument-equalizer}, in
+@file{../scm/midi.scm} shows how such a procedure might be written.
+
+The following example sets the relative flute and clarinet volumes
+to the same values as the previous example.
+
+@lilypond[verbatim,quote]
+#(define my-instrument-equalizer-alist '())
+
+#(set! my-instrument-equalizer-alist
+  (append
+    '(
+      ("flute" . (0.7 . 0.9))
+      ("clarinet" . (0.3 . 0.6)))
+    my-instrument-equalizer-alist))
+
+#(define (my-instrument-equalizer s)
+  (let ((entry (assoc s my-instrument-equalizer-alist)))
+    (if entry
+      (cdr entry))))
+
+\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 ~
+        fis4 g8 fis e2 ~
+        e4 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 {
+    \context {
+      \Score
+      tempoWholesPerMinute = #(ly:make-moment 72 2)
+    }
+  }
+}
+@end lilypond
+
+@ignore
+@c Delete when satisfied this is adequately covered elsewhere -td
+
+@n ode Microtones in MIDI
+@s ubsection Microtones in MIDI
 
 @cindex microtones in MIDI
 
@@ -1595,15 +1879,37 @@ copied out and compiled to test microtones in your MIDI player.
   \midi {}
 }
 @end lilypond
+@end ignore
 
-@knownissues
 
-@c TODO List things that have no effect
-@c TODO Check these
+@node Percussion in MIDI
+@subsection Percussion in MIDI
+
+Percussion instruments are generally notated in a @code{DrumStaff}
+context and when notated in this way they are outputted correctly
+to MIDI channel@tie{}10, but some pitched percussion instruments,
+like the xylophone, marimba, vibraphone, timpani, etc., are
+treated like @qq{normal} instruments and music for these instruments
+should be entered in a normal @code{Staff} context, not a
+@code{DrumStaff} context, to obtain the correct MIDI output.
 
-Many musically interesting effects, such as swing, articulation,
-slurring, etc., are not translated to midi.  Also, figured bass,
-chords, and lyrics have no effect on MIDI.
+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.
+
+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.
+
+@c TODO Expand with examples, and any other issues
+
+@knownissues
 
+Because the general MIDI standard does not contain rim shots, the
+sidestick is used for this purpose instead.