Update from Andrew: tweaks for cross-staff chords snippet.

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

diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely
index 35948d78e8c2b7153233ee7d3afff42ce34dafa6..7c199fef71247d4aa649605d8153b8f529547f61 100644 (file)
--- 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
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

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

 
 

-@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
 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
 
 


@@ -337,10 +337,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
 
 


@@ -428,13 +428,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" }


@@ -760,10 +760,10 @@ Init files: @file{../ly/@/toc@/-init@/.ly}.
 @section Working with input files
 
 @menu
 @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
 
 


@@ -885,8 +885,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


@@ -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
 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
 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:
 
 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 {
   Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
 % Cyrillic
 bulgarian = \lyricmode {
   Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.


@@ -1223,8 +1224,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


@@ -1331,13 +1332,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?::
-* MIDI instrument names::
-* Repeats in MIDI::
-* Controlling MIDI dynamics::
-* Microtones 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


@@ -1392,16 +1392,16 @@ The MIDI instrument to be used is specified by setting the
 The name should be chosen from the list in @ref{MIDI instruments}.
 
 @example
 The name should be chosen from the list in @ref{MIDI instruments}.
 
 @example

-\new Staff {
+\new Staff @{

   \set Staff.midiInstrument = "glockenspiel"
   @var{...notes...}
   \set Staff.midiInstrument = "glockenspiel"
   @var{...notes...}

-}
+@}

 @end example
 
 @example
 @end example
 
 @example

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

   @var{...notes...}
   @var{...notes...}

-}
+@}

 @end example
 
 If the selected instrument does not exactly match an instrument from
 @end example
 
 If the selected instrument does not exactly match an instrument from


@@ -1629,7 +1629,7 @@ required fraction, and setting
 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
 
 For example, if a @notation{rinforzando} dynamic marking,
 @code{Score.dynamicAbsoluteVolumeFunction} to this function.
 
 For example, if a @notation{rinforzando} dynamic marking,

-@code{\rfz), is required, this will not by default
+@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
 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


@@ -1839,8 +1839,8 @@ to the same values as the previous example.
 @ignore
 @c Delete when satisfied this is adequately covered elsewhere -td
 
 @ignore
 @c Delete when satisfied this is adequately covered elsewhere -td
 

-@node Microtones in MIDI
-@subsection Microtones in MIDI
+@n ode Microtones in MIDI
+@s ubsection Microtones in MIDI

 
 @cindex microtones in MIDI
 
 
 @cindex microtones in MIDI
 


@@ -1864,7 +1864,37 @@ copied out and compiled to test microtones in your MIDI player.
   \midi {}
 }
 @end lilypond
   \midi {}
 }
 @end lilypond

-@end ingore
+@end ignore
+
+
+@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.
+
+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.