Doc-de: update macros.itely and nitpicks

[lilypond.git] / Documentation / user / input.itely

diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely
index 03fdba03fe87aae47fddb400cf547897842a0caf..ead89488c46b67a63e918c886467f8fcb8c8093f 100644 (file)
--- a/Documentation/user/input.itely
+++ b/Documentation/user/input.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.51"
+@c \version "2.12.0"

 
 @node General input and output
 @chapter General input and output
 
 @node General input and output
 @chapter General input and output


@@ -16,11 +16,11 @@ This section deals with general LilyPond input and output issues,
 rather than specific notation.
 
 @menu
 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
 
 
 @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
 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
 
 
 @end menu
 
 


@@ -99,10 +99,9 @@ input file.  They may be placed inside or outside a @code{\score}
 block, and inside or outside the single music expression within a
 @code{\score} block.
 
 block, and inside or outside the single music expression within a
 @code{\score} block.
 

-@seealso

 
 

+@seealso

 Learning Manual:
 Learning Manual:

-

 @rlearning{Working on input files},
 @rlearning{Music expressions explained},
 @rlearning{Score is a (single) compound musical expression}.
 @rlearning{Working on input files},
 @rlearning{Music expressions explained},
 @rlearning{Score is a (single) compound musical expression}.


@@ -185,6 +184,30 @@ the top of the file is inserted.
 @}
 @end example
 
 @}
 @end example
 

+@funindex \bookpart
+
+Pieces of music may be grouped into book parts using @code{\bookpart}
+blocks.  Book parts are separated by a page break, and can start with a
+title, like the book itself, by specifying a @code{\header} block.
+
+@example
+\bookpart @{
+  \header @{
+    title = "Book title"
+    subtitle = "First part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+\bookpart @{
+  \header @{
+    subtitle = "Second part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+@end example
+

 @node File structure
 @subsection File structure
 
 @node File structure
 @subsection File structure
 


@@ -194,6 +217,7 @@ the top of the file is inserted.
 @funindex \header
 @funindex \score
 @funindex \book
 @funindex \header
 @funindex \score
 @funindex \book

+@funindex \bookpart

 
 A @code{.ly} file may contain any number of toplevel expressions, where a
 toplevel expression is one of the following:
 
 A @code{.ly} file may contain any number of toplevel expressions, where a
 toplevel expression is one of the following:


@@ -238,6 +262,11 @@ changed by setting the variable @code{toplevel-book-handler} at
 toplevel.  The default handler is defined in the init file
 @file{../scm/@/lily@/.scm}.
 
 toplevel.  The default handler is defined in the init file
 @file{../scm/@/lily@/.scm}.
 

+@item
+A @code{\bookpart} block.  A book may be divided into several parts,
+using @code{\bookpart} blocks, in order to ease the page breaking,
+or to use different @code{\paper} settings in different parts.
+

 @item
 A compound music expression, such as
 @example
 @item
 A compound music expression, such as
 @example


@@ -287,7 +316,7 @@ foo = @{ c4 d e d @}
 @end example
 
 This can be used later on in the file by entering @code{\foo}.  The
 @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
 numbers, underscores or dashes.
 
 @end itemize


@@ -325,11 +354,33 @@ A multi-line comment delimited by @code{%@{ .. %@}}.
 
 @end itemize
 
 
 @end itemize
 

-@seealso
+@cindex whitespace
+
+Whitespace between items in the input stream is generally ignored,
+and may be freely omitted or extended to enhance readability.
+However, whitespace should always be used in the following
+circumstances to avoid errors:

 
 

+@itemize
+@item Around every opening and closing curly bracket.
+@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.
+@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
+must be used around the dot and the equals sign in commands like
+@code{\override Score . LyricText #'font-size = #5} and before and
+after the entire command.
+
+@end itemize
+
+@seealso

 Learning Manual:
 @rlearning{How LilyPond input files work}.
 
 Learning Manual:
 @rlearning{How LilyPond input files work}.
 

+

 @node Titles and headers
 @section Titles and headers
 
 @node Titles and headers
 @section Titles and headers
 


@@ -337,10 +388,10 @@ Almost all printed music includes a title and the composer's name;
 some pieces include a lot more information.
 
 @menu
 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
 
 
 @end menu
 
 


@@ -348,7 +399,8 @@ some pieces include a lot more information.
 @subsection Creating titles
 
 Titles are created for each @code{\score} block, as well as for the full
 @subsection Creating titles
 
 Titles are created for each @code{\score} block, as well as for the full

-input file (or @code{\book} block).
+input file (or @code{\book} block) and book parts (created by
+@code{\bookpart} blocks).

 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following


@@ -373,32 +425,32 @@ Subsubtitle, centered below the subtitle.
 
 @funindex poet
 @item poet
 
 @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
 
 @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 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
 @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
 
 @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
 
 @cindex page breaks, forcing
 @funindex breakbefore


@@ -428,13 +480,13 @@ may use any @ref{Formatting text}, commands in the header.
 \book {
   \header {
     dedication = "dedicated to me"
 \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"
 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" }
     texttranslator = "Text Translator"
     meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
 "r" }


@@ -498,14 +550,14 @@ Note that the music expression must come before the @code{\header}.
 }
 @end lilypond
 
 }
 @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@{
 @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
 
 @}
 @end example
 


@@ -635,12 +687,14 @@ the markup have to be known before, so a gauge is used to decide these
 dimensions.  If the book has between 10 and 99 pages, it may be "00",
 ie. a two digit number.
 
 dimensions.  If the book has between 10 and 99 pages, it may be "00",
 ie. a two digit number.
 

-@predefined

 
 

+@predefined

 @funindex \label
 @funindex \label

-@code{\label}
+@code{\label},

 @funindex \page-ref
 @funindex \page-ref

-@code{\page-ref}
+@code{\page-ref}.
+@endpredefined
+

 
 @node Table of contents
 @subsection Table of contents
 
 @node Table of contents
 @subsection Table of contents


@@ -744,26 +798,27 @@ tocAct =
 }
 @end lilypond
 
 }
 @end lilypond
 

-@seealso

 
 

+@seealso

 Init files: @file{../ly/@/toc@/-init@/.ly}.
 
 Init files: @file{../ly/@/toc@/-init@/.ly}.
 

-@predefined

 
 

+@predefined

 @funindex \table-of-contents
 @funindex \table-of-contents

-@code{\table-of-contents}
+@code{\table-of-contents},

 @funindex \tocItem
 @funindex \tocItem

-@code{\tocItem}
+@code{\tocItem}.
+@endpredefined

 
 
 @node Working with input files
 @section Working with input files
 
 @menu
 
 
 @node Working with input files
 @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
 
 
 @end menu
 
 


@@ -815,11 +870,19 @@ subdirectory called @file{parts} within the current directory, use
 @end example
 
 Files which are to be included can also contain @code{\include}
 @end example
 
 Files which are to be included can also contain @code{\include}

-statements of their own.  These second-level
+statements of their own.  By default, these second-level

 @code{\include} statements are not interpreted until they have
 been brought into the main file, so the file names they specify
 must all be relative to the directory containing the main file,
 @code{\include} statements are not interpreted until they have
 been brought into the main file, so the file names they specify
 must all be relative to the directory containing the main file,

-not the directory containing the included file.
+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
+(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
+relative to the file containing that command. This behavior is
+recommended and it will become the default behavior in a future
+version of lilypond.

 
 Files can also be included from a directory in a search path
 specified as an option when invoking LilyPond from the command
 
 Files can also be included from a directory in a search path
 specified as an option when invoking LilyPond from the command


@@ -842,28 +905,32 @@ and in main.ly write
 
 Files which are to be included in many scores may be placed in
 the LilyPond directory @file{../ly}.  (The location of this
 
 Files which are to be included in many scores may be placed in
 the LilyPond directory @file{../ly}.  (The location of this

-directory is installation-dependent - see @rlearning{Other sources
-of information}).  These files can then be included simply by
-naming them on an @code{\include} statement.  This is how the
-language-dependent files like @file{english.ly} are included.
+directory is installation-dependent - see
+@rlearning{Other sources of information}).  These files can then
+be included simply by naming them on an @code{\include} statement.
+This is how the language-dependent files like @file{english.ly} are
+included.

 
 LilyPond includes a number of files by default when you start
 the program.  These includes are not apparent to the user, but the
 files may be identified by running @code{lilypond --verbose} from
 the command line.  This will display a list of paths and files that
 LilyPond uses, along with much other information.  Alternatively,
 
 LilyPond includes a number of files by default when you start
 the program.  These includes are not apparent to the user, but the
 files may be identified by running @code{lilypond --verbose} from
 the command line.  This will display a list of paths and files that
 LilyPond uses, along with much other information.  Alternatively,

-the more important of these files are discussed in @rlearning{Other
-sources of information}.  These files may be edited, but changes to
-them will be lost on installing a new version of LilyPond.
+the more important of these files are discussed in
+@rlearning{Other sources of information}.  These files may be
+edited, but changes to them will be lost on installing a new
+version of LilyPond.

 
 Some simple examples of using @code{\include} are shown in
 @rlearning{Scores and parts}.
 
 
 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}.
 
 @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
 @knownissues
 
 If an included file is given a name which is the same as one in


@@ -885,8 +952,8 @@ the structure of the score will make it easier to change the
 structure while leaving the notation untouched.
 
 @menu
 structure while leaving the notation untouched.
 
 @menu

-* Using variables::             
-* Using tags::                  
+* Using variables::
+* Using tags::

 @end menu
 
 @node Using variables
 @end menu
 
 @node Using variables


@@ -1083,8 +1150,8 @@ 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.
 
 the first filter will remove all tagged sections except the one
 named, and the second filter will remove even that tagged section.
 

-@seealso

 
 

+@seealso

 Learning Manual:
 @rlearning{Organizing pieces with variables}.
 
 Learning Manual:
 @rlearning{Organizing pieces with variables}.
 


@@ -1092,6 +1159,7 @@ Notation Reference:
 @ref{Automatic part combining},
 @ref{Including LilyPond files}.
 
 @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.
 @ignore
 @c This warning is more general than this placement implies.
 @c Rests are not merged whether or not they come from tagged sections.


@@ -1107,6 +1175,10 @@ than one tagged section at the same place.
 @node Text encoding
 @subsection Text encoding
 
 @node Text encoding
 @subsection 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
 code point for the character sets used in virtually all modern
 LilyPond uses the character repertoire defined by the Unicode
 consortium and ISO/IEC 10646.  This defines a unique name and
 code point for the character sets used in virtually all modern


@@ -1122,7 +1194,7 @@ the mapping of a subset of the Unicode code points to glyphs.
 LilyPond uses the Pango library to layout and render multi-lingual
 texts.
 
 LilyPond uses the Pango library to layout and render multi-lingual
 texts.
 

-Lilypond does not perform any input-encoding conversions.  This
+LilyPond does not perform any input-encoding conversions.  This

 means that any text, be it title, lyric text, or musical
 instruction containing non-ASCII characters, must be encoded in
 UTF-8.  The easiest way to enter such text is by using a
 means that any text, be it title, lyric text, or musical
 instruction containing non-ASCII characters, must be encoded in
 UTF-8.  The easiest way to enter such text is by using a


@@ -1170,23 +1242,50 @@ portuguese = \lyricmode {
 \addlyrics { \portuguese }
 @end lilypond
 
 \addlyrics { \portuguese }
 @end lilypond
 

-To enter a single character for which the Unicode escape sequence
-is known but which is not available in the editor being used, enter
+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
+@code{\markup} block, where @code{hhhh} is the hexadecimal code for
+the character required and @code{dddd} is the corresponding decimal
+value.  Leading zeroes may be omitted, but it is usual to specify
+all four characters in the hexadecimal representation.  (Note that
+the UTF-8 encoding of the code point should @emph{not} be used
+after @code{\char}, as UTF-8 encodings contain extra bits indicating
+the number of octets.)
+
+For example, @code{\char ##x03BE} and @code{\char #958} would both
+enter the Unicode U+03BE character, which has the Unicode name
+@qq{Greek Small Letter Xi}.
+
+Any Unicode code point may be entered in this way 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 Unicode hexadecimal values being entered
+in four places -- in a rehearsal mark, as articulation text, in
+lyrics and as stand-alone text below the score:

 
 

-@example
-#(ly:export (ly:wide-char->utf-8 #x03BE))
-@end example
+@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--2009" \char ##x00A9 }
+@end lilypond

 
 

-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.
+@cindex copyright sign

 
 

-@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
 
 @node Displaying LilyPond notation
 @subsection Displaying LilyPond notation


@@ -1224,8 +1323,8 @@ lilypond file.ly >display.txt
 @section Controlling output
 
 @menu
 @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
 @end menu
 
 @node Extracting fragments of music


@@ -1268,6 +1367,7 @@ For more information on output formats, see @rprogram{Invoking lilypond}.
 
 
 @funindex skipTypesetting
 
 
 @funindex skipTypesetting

+@funindex showFirstLength

 @funindex showLastLength
 
 When entering or copying music, usually only the music near the end (where
 @funindex showLastLength
 
 When entering or copying music, usually only the music near the end (where


@@ -1285,7 +1385,9 @@ showLastLength = R1*5
 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
 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
+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),
+the @code{showFirstLength} property may be useful as well.

 
 Skipping parts of a score can be controlled in a more fine-grained
 fashion with the property @code{Score.skipTypesetting}.  When it is
 
 Skipping parts of a score can be controlled in a more fine-grained
 fashion with the property @code{Score.skipTypesetting}.  When it is


@@ -1332,12 +1434,12 @@ 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
 (or 14 if you do not use drums).  Other staves will remain silent.
 
 @menu

-* Creating MIDI files::         
-* MIDI block::                  
-* What goes into the MIDI output?::  
-* Repeats in MIDI::             
-* Controlling MIDI dynamics::   
-* Percussion in MIDI::          
+* 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
 @end menu
 
 @node Creating MIDI files


@@ -1382,6 +1484,26 @@ 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}.
 
 of specifying the inital or overall MIDI tempo is described below,
 see @ref{MIDI block}.
 

+Due to some limitations on Windows, the default extension for
+MIDI files on Windows is @code{.mid}. Other operating systems still
+use the extension @code{.midi}. If a different extension is preferred,
+insert the following line at the top-level of the input file,
+before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
+
+@example
+#(ly:set-option 'midi-extension "midi")
+@end example
+
+The line above will set the default extension for MIDI files to
+@code{.midi}.
+
+Alternatively, this option can also be supplied on the command line:
+
+@example
+lilypond … -dmidi-extension=midi lilyFile.ly
+@end example
+
+

 @unnumberedsubsubsec Instrument names
 
 @cindex instrument names
 @unnumberedsubsubsec Instrument names
 
 @cindex instrument names


@@ -1393,13 +1515,13 @@ The name should be chosen from the list in @ref{MIDI instruments}.
 
 @example
 \new Staff @{
 
 @example
 \new Staff @{

-  \set Staff.midiInstrument = "glockenspiel"
+  \set Staff.midiInstrument = #"glockenspiel"

   @var{...notes...}
 @}
 @end example
 
 @example
   @var{...notes...}
 @}
 @end example
 
 @example

-\new Staff \with @{midiInstrument = "cello"@} @{
+\new Staff \with @{midiInstrument = #"cello"@} @{

   @var{...notes...}
 @}
 @end example
   @var{...notes...}
 @}
 @end example


@@ -1538,7 +1660,7 @@ The following items of notation are reflected in the MIDI output:
 
 @itemize
 @item Pitches
 
 @itemize
 @item Pitches

-@item Quarter tones (See @ref{Accidentals}. Rendering needs a
+@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
 player that supports pitch bend.)
 @item Chords entered as chord names
 @item Rhythms entered as note durations, including tuplets


@@ -1547,6 +1669,7 @@ player that supports pitch bend.)
 @item Dynamic marks
 @item Crescendi, decrescendi over multiple notes
 @item Tempo changes entered with a tempo marking
 @item Dynamic marks
 @item Crescendi, decrescendi over multiple notes
 @item Tempo changes entered with a tempo marking

+@item Lyrics

 @end itemize
 
 @unnumberedsubsubsec Unsupported in MIDI
 @end itemize
 
 @unnumberedsubsubsec Unsupported in MIDI


@@ -1563,8 +1686,7 @@ The following items of notation have no effect on the MIDI output:
 @item Crescendi, decrescendi over a single note
 @item Tremolos entered with @q{@code{:}[@var{number}]}
 @item Figured bass
 @item Crescendi, decrescendi over a single note
 @item Tremolos entered with @q{@code{:}[@var{number}]}
 @item Figured bass

-@c TODO Check Lyrics
-@item Lyrics
+@item Microtonal chords

 @end itemize
 
 
 @end itemize
 
 


@@ -1646,7 +1768,7 @@ found, or calls the default function otherwise.
 
 \score {
   \new Staff {
 
 \score {
   \new Staff {

-    \set Staff.midiInstrument = "cello"
+    \set Staff.midiInstrument = #"cello"

     \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
     \new Voice {
        \relative c'' {
     \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
     \new Voice {
        \relative c'' {


@@ -1870,37 +1992,31 @@ copied out and compiled to test microtones in your MIDI player.
 @node Percussion in MIDI
 @subsection Percussion in MIDI
 
 @node Percussion in MIDI
 @subsection Percussion in MIDI
 

-@c FIXME: sorry Trevor, I know this is a complete mess.  :(
-
-But You should be aware,  that some percussion sounds cannot be
-reached via the  @code{DrumStaff} context. Pitched percussion
-sounds,  like
-Xylophone, Marimaphone, Vibraphone, Timpani, etc. are treated like
-"normal" instruments and You should input music for these
-instruments in a @code{Staff} context, not in a @code{DrumStaff}
-context.
-Too make it more complicated:
-some  non pitched percussion sounds  of the general midi standard,
-like "melodic-tom", "taiko-drum" "synth drum", etc. cannot
-be reached via midi-channel 10, so You should also  use for them a
-@code{ Staff} context, with "normal" pitches. And, last but not
-least,
-it should be mentioned, that there are lots of percussion
-instruments, which are note part of the general midi standard.
-If You want to  write for e.g. castanets, You have to find a
-substitution for this sound (or have a good sampler).
-But let us forget for this moment the limitations of midi and let
-us go on with some more examples, that show You how to write
-for percussion instruments with Lilypond:
-
-@c (no, seriously, there was no example here.  I didn't just forget
-@c to copy it.  -gp)
+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.
+
+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
 
 
 @knownissues
 

-Because general MIDI does not contain rim shots, the sidestick is
-used for this purpose instead.
+Because the general MIDI standard does not contain rim shots, the
+sidestick is used for this purpose instead.