From d9222eec25ca8143e7e84a5af61aaa98acec5e6a Mon Sep 17 00:00:00 2001
From: Devon Schudy <dschudy@gmail.com>
Date: Sun, 15 Dec 2013 17:27:00 -0500
Subject: [PATCH] Update documentation for what's supported in MIDI. (issue
 3740)

Also clarify what articulate.ly supports.

Change the snippet for redefining a shorthand to use an ArticulationEvent
instead of an articulation name, so users who follow its example will have
their articulations work in MIDI.
---
 Documentation/changes.tely                    | 10 ++++++++++
 Documentation/notation/input.itely            | 19 +++++++++++--------
 ...ues-for-articulation-shorthand-notation.ly |  8 ++++----
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 4ea92a7cb3..5697aa69cb 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -61,6 +61,16 @@ which scares away people.
 
 @end ignore
 
+@item
+The most common articulations are now reflected in MIDI output.
+Accent and marcato make notes louder; staccato, staccatissimo and
+portato make them shorter. Breath marks shorten the previous
+note.
+
+This behavior is customizable through the @code{midiLength} and
+@code{midiExtraVelocity} properties on @code{ArticulationEvent}.
+See @file{script-init.ly} for examples.
+
 @item
 The PostScript functionality of stroke adjustment is no longer
 applied automatically but left to the discretion of the PostScript
diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index 1617a39395..b00045230f 100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -2884,15 +2884,17 @@ player that supports pitch bend.)
 @item Crescendi, decrescendi over multiple notes
 @item Tempo changes entered with a tempo marking
 @item Lyrics
+@item Simple articulations: staccato, staccatissimo, accent, marcato, portato
+@item @ref{Breath marks}
 @end itemize
 
-Using @ref{The Articulate script}, a number of items are added to the
-above list:
+There is a script that adds the following items; see
+@ref{The Articulate script}:
 
 @itemize
-@item Articulations (slurs, staccato, etc)
-@item Trills, turns
-@item Rallentando and accelerando
+@item Slurs and phrasing slurs
+@item Ornaments (mordents, trills, turns, etc.)
+@item Rallentando, accelerando, ritard, and a tempo
 @end itemize
 
 
@@ -2902,17 +2904,18 @@ above list:
 @c TODO index as above
 
 The following items of notation have no effect on the MIDI output,
-unless you use @ref{The Articulate script}:
+even if you use @ref{The Articulate script}:
 
 @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 Fermatas
+@item Other articulations
 @item Crescendi, decrescendi over a single note
 @item Tremolos entered with @q{@code{:}[@var{number}]}
 @item Figured bass
 @item Microtonal chords
+@item Glissandi, falls and doits
 @end itemize
 
 
diff --git a/Documentation/snippets/modifying-default-values-for-articulation-shorthand-notation.ly b/Documentation/snippets/modifying-default-values-for-articulation-shorthand-notation.ly
index a2553ad84e..1c1fcd1019 100644
--- a/Documentation/snippets/modifying-default-values-for-articulation-shorthand-notation.ly
+++ b/Documentation/snippets/modifying-default-values-for-articulation-shorthand-notation.ly
@@ -14,9 +14,9 @@ The shorthands are defined in @samp{ly/script-init.ly}, where the
 variables @code{dashHat}, @code{dashPlus}, @code{dashDash},
 @code{dashBang}, @code{dashLarger}, @code{dashDot}, and
 @code{dashUnderscore} are assigned default values.  The default values
-for the shorthands can be modified. For example, to associate the
-@code{-+} (@code{dashPlus}) shorthand with the trill symbol instead of
-the default + symbol, assign the value @code{trill} to the variable
+for the shorthands can be modified. For example, to make the @code{-+}
+(@code{dashPlus}) shorthand create a trill instead of the default +
+(@code{stopped}), assign the value of @code{trill} to the variable
 @code{dashPlus}:
 
 "
@@ -26,6 +26,6 @@ the default + symbol, assign the value @code{trill} to the variable
 
 \relative c'' { c1-+ }
 
-dashPlus = "trill"
+dashPlus = \trill
 
 \relative c'' { c1-+ }
-- 
2.39.5