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 a61d56b231bdbdc2ce4e62fe173f3b389437fead..067b7f47711a6841feefa5ddadd2a8b37acc71a5 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -957,6 +957,22 @@ tocAct =
 }
 @end lilypond
 
+Dots can be added to fill the line between an item and its page number:
+
+@lilypond[verbatim,quote]
+\header { tagline = ##f }
+\paper {
+  tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+  \markuplines \table-of-contents
+  \tocItem \markup { Allegro }
+  \tocItem \markup { Largo }
+  \markup \null
+}
+@end lilypond
+
 
 @seealso
 Init files: @file{../ly/toc-init.ly}.
@@ -1113,6 +1129,7 @@ structure while leaving the notation untouched.
 @menu
 * Using variables::
 * Using tags::
+* Using global settings::
 @end menu
 
 @node Using variables
@@ -1331,6 +1348,33 @@ than one tagged section at the same place.
 
 @end ignore
 
+@node Using global settings
+@unnumberedsubsubsec Using global settings
+
+@cindex include-settings
+
+Global settings can be included from a separate file:
+
+@example
+lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
+@end example
+
+Groups of settings such as page size, font or type face can be stored
+in separate files. This allows different editions from the same score
+as well as standard settings to be applied to many scores, simply by
+specifying the proper settings file.
+
+This technique also works well with the use of style sheets, as
+discussed in @rlearning{Style sheets}.
+
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables},
+@rlearning{Style sheets}.
+
+Notation Reference:
+@ref{Including LilyPond files}.
+
 @node Text encoding
 @subsection Text encoding
 
@@ -1436,7 +1480,7 @@ lyrics and as stand-alone text below the score:
   }
   \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
 }
-\markup { "Copyright 2008--2010" \char ##x00A9 }
+\markup { "Copyright 2008--2011" \char ##x00A9 }
 @end lilypond
 
 @cindex copyright sign
@@ -1642,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
@@ -1654,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
@@ -1864,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:
@@ -1882,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
@@ -2229,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.