X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpercussion.itely;h=afed901cc94e8b9bfdfac1ab7ff0a8617cf08ef9;hb=edf17353d89f4f6bd831466262402bb9151a26ca;hp=f52970f8f04a538e08e9cf5c3f3556bb0c876a85;hpb=c7a0e5ce35a422e99d342c5fdcf9675352993bb8;p=lilypond.git

diff --git a/Documentation/user/percussion.itely b/Documentation/user/percussion.itely
index f52970f8f0..afed901cc9 100644
--- a/Documentation/user/percussion.itely
+++ b/Documentation/user/percussion.itely
@@ -6,48 +6,42 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
+@c \version "2.11.51"
+
 @node Percussion
 @section Percussion
 
 @menu
-* Percussion sections::         
+* Common notation for percussion::
 @end menu
 
-@node Percussion sections
-@subsection Percussion sections
+@node Common notation for percussion
+@subsection Common notation for percussion
 
 Rhythmic music is primarily used for percussion and drum notation, but it can
 also be used to show the rhythms of melodies.
 
 @menu
-* Showing melody rhythms::      
-* Entering percussion::         
-* Percussion staves::           
-* Ghost notes::                 
+* References for percussion::
+* Basic percussion notation::
+* Percussion staves::
+* Ghost notes::
 @end menu
 
+@node References for percussion
+@subsubsection References for percussion
 
-@node Showing melody rhythms
-@subsubsection Showing melody rhythms
+@c TODO Add refs
+TBC
 
-Sometimes you might want to show only the rhythm of a melody.  This
-can be done with the rhythmic staff.  All pitches of notes on such a
-staff are squashed, and the staff itself has a single line
-
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-\new RhythmicStaff {
-  \time 4/4
-  c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
-}
-@end lilypond
 
 @seealso
 
-Internals Reference: @internalsref{RhythmicStaff}.
+Internals Reference: @rinternals{RhythmicStaff}.
 
 
-@node Entering percussion
-@subsubsection Entering percussion
+@node Basic percussion notation
+@subsubsection Basic percussion notation
 
 @cindex percussion
 @cindex drums
@@ -55,8 +49,10 @@ Internals Reference: @internalsref{RhythmicStaff}.
 
 Percussion notes may be entered in @code{\drummode} mode, which is
 similar to the standard mode for entering notes.  Each piece of
-percussion has a full name and an abbreviated name, and both can be used
-in input files
+percussion has a full name and an abbreviated name, and both can
+be used in input files.  The simplest way to enter percussion notes
+is to use the @code{\drums} command, which creates the correct
+context and entry mode for percussion:
 
 @lilypond[quote,ragged-right,verbatim]
 \drums {
@@ -64,13 +60,48 @@ in input files
 }
 @end lilypond
 
+This is shorthand for
+
+@lilypond[quote,ragged-right,verbatim]
+\new DrumStaff
+\drummode {
+  hihat hh bassdrum bd
+}
+@end lilypond
+
+
 The complete list of drum names is in the init file
 @file{ly/@/drumpitch@/-init@/.ly}.
 @c TODO: properly document this.
 
+Drum rolls are indicated with three slashes across the stem.
+For quarter notes or longer the three slashes are shown explicitly,
+eighth notes are shown with two slashes (the beam being the third),
+and drum rolls shorter than eighths have one stem slash to
+supplement the beams.  This is achieved with the tremolo notation,
+@code{:32}, see @ref{Tremolo repeats}.  Here's an example of
+some snare rolls:
+
+@lilypond[quote,ragged-right,verbatim]
+\new DrumStaff
+\drummode {
+  \time 2/4
+  sn16 sn8 sn16 sn8 sn8:32~ |
+  sn8 sn8 sn4:32~ |
+  sn4 sn8 sn16 sn16 |
+  sn4 r4 |
+}
+@end lilypond
+
+Sticking can be indicated by placing @code{^"R"} or @code{^"L"}
+after the note.  The @code{staff-padding} property may be
+overridden to achieve a pleasing baseline.
+
+@c TODO Add example of sticking
+
 @seealso
 
-Internals Reference: @internalsref{note-event}.
+Internals Reference: @rinternals{note-event}.
 
 @node Percussion staves
 @subsubsection Percussion staves
@@ -83,7 +114,7 @@ of percussion.
 
 
 To typeset the music, the notes must be interpreted in a
-@internalsref{DrumStaff} and @internalsref{DrumVoice} contexts
+@rinternals{DrumStaff} and @rinternals{DrumVoice} contexts
 
 @lilypond[quote,ragged-right,verbatim]
 up = \drummode { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
@@ -95,8 +126,8 @@ down = \drummode { bassdrum4 snare8 bd r bd sn4 }
 @end lilypond
 
 The above example shows verbose polyphonic notation.  The short
-polyphonic notation, described in @rlearning{I'm seeing Voices},
-can also be used if the @internalsref{DrumVoice}s are instantiated
+polyphonic notation, described in @rlearning{I'm hearing Voices},
+can also be used if the @rinternals{DrumVoice}s are instantiated
 by hand first.  For example,
 
 @lilypond[quote,ragged-right,fragment,verbatim]
@@ -116,7 +147,7 @@ by hand first.  For example,
 
 
 There are also other layout possibilities.  To use these, set the
-property @code{drumStyleTable} in context @internalsref{DrumVoice}.
+property @code{drumStyleTable} in context @rinternals{DrumVoice}.
 The following variables have been predefined
 
 @table @code
@@ -281,9 +312,9 @@ down = \drummode { bd4 sn bd toml8 toml }
 
 Init files: @file{ly/@/drumpitch@/-init@/.ly}.
 
-Internals Reference: @internalsref{DrumStaff}, @internalsref{DrumVoice}.
+Internals Reference: @rinternals{DrumStaff}, @rinternals{DrumVoice}.
 
-@refbugs
+@knownissues
 
 Because general MIDI does not contain rim shots, the sidestick is used
 for this purpose instead.
@@ -297,9 +328,7 @@ Ghost notes for drums and percussion may be created using the
 @code{\parenthesize} command detailed in @ref{Parentheses}.  However,
 the default @code{\drummode} does
 not include the @code{Parenthesis_engraver} plugin which allows
-this.  You
-must add the plugin explicitly in the context definition as
-detailed in @ref{Changing context properties on the fly}.
+this.
 
 @lilypond[quote,ragged-right,verbatim,fragment]
 \new DrumStaff \with {