Include and document the Articulate script by Peter Chubb.

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

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index a7b36aac63f9029e5c1bfdfead6bc7490dc9ea4e..067b7f47711a6841feefa5ddadd2a8b37acc71a5 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -1353,7 +1353,7 @@ than one tagged section at the same place.
 
 @cindex include-settings
 
-Global settings can be incuded from a separate file:
+Global settings can be included from a separate file:
 
 @example
 lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
@@ -1686,6 +1686,10 @@ 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
+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
@@ -1698,6 +1702,7 @@ settings.  Therefore the midi file should not have more than 15 staves
 * Repeats in MIDI::
 * Controlling MIDI dynamics::
 * Percussion in MIDI::
+* The Articulate script::
 @end menu
 
 @node Creating MIDI files
@@ -1908,6 +1913,13 @@ within a score block defined with a @code{\score} command.
 @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:
@@ -1926,11 +1938,22 @@ player that supports pitch bend.)
 @item Lyrics
 @end itemize
 
+Using @ref{The Articulate script}, a number of items are added to the
+above list:
+
+@itemize
+@item Articulations (slurs, staccato, etc)
+@item Trills, turns
+@item Rallentando and accelerando
+@end itemize
+
+
 @unnumberedsubsubsec Unsupported in MIDI
 
 @c TODO index as above
 
-The following items of notation have no effect on the MIDI output:
+The following items of notation have no effect on the MIDI output,
+unless you use @ref{The Articulate script}:
 
 @itemize
 @item Rhythms entered as annotations, e.g. swing
@@ -2273,4 +2296,40 @@ set.
 Because the general MIDI standard does not contain rim shots, the
 sidestick is used for this purpose instead.
 
+@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.
+
+To use the Articulate script, you have to include it at the top of
+your input file,
+
+@example
+\include "articulate.ly"
+@end example
+
+and in the @code{\score} section do
+
+@example
+\unfoldRepeats \articulate <<
+       all the rest of the score...
+>>
+@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}.
+
+@knownissues
 
+Articulate shortens chords and some music (esp. organ music) could
+sound worse.