Doc: Improve clef documentation in NR

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

diff --git a/Documentation/notation/percussion.itely b/Documentation/notation/percussion.itely
index f182b78a9ac80c0f0ee332199fe05bd8e16dda39..a41a53a03a264da0fb55882f20483daba632caed 100644 (file)
--- a/Documentation/notation/percussion.itely
+++ b/Documentation/notation/percussion.itely
@@ -3,7 +3,8 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
-    version that you are working on.  See TRANSLATION for details.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..
 @end ignore
 
 @c \version "2.12.0"
@@ -54,7 +55,8 @@ Notation Reference:
 @ref{Instantiating new staves}.
 @ref{Percussion in MIDI}.
 
-Snippets: @rlsr{Percussion}.
+Snippets:
+@rlsr{Percussion}.
 
 
 @node Basic percussion notation
@@ -88,21 +90,39 @@ Each piece of percussion has a full name and an abbreviated name,
 and both can be used in input files.  The full list of percussion
 note names may be found in @ref{Percussion notes}.
 
-Note that the normal notation of pitches (such as @code{cis4}) in
-a @code{DrumStaff} context will cause an error message.
-Percussion clefs are added automatically to a @code{DrumStaff}
-contex, but other clefs may also be used.
+@cindex clef, percussion
+@cindex percussion clef
+
+Note that the normal notation of pitches (such as @code{cis4}) in a
+@code{DrumStaff} context will cause an error message. Percussion clefs
+are added automatically to a @code{DrumStaff} context but they can also
+be set explicitly.  Other clefs may be used as well.
+
+@lilypond[quote,ragged-right,verbatim]
+\drums {
+  \clef treble
+  hh4 hh hh hh
+  \break
+  \clef percussion
+  bd4 bd bd bd
+}
+@end lilypond
+
 
 There are a few issues concerning MIDI support for percussion
 instruments; for details please see @ref{Percussion in MIDI}.
 
 
 @seealso
-Notation Reference: @ref{Percussion in MIDI}, @ref{Percussion notes}.
+Notation Reference:
+@ref{Percussion in MIDI},
+@ref{Percussion notes}.
 
-File: @file{ly/@/drumpitch@/-init@/.ly}
+File:
+@file{ly/@/drumpitch@/-init@/.ly}
 
-Snippets: @rlsr{Percussion}.
+Snippets:
+@rlsr{Percussion}.
 
 
 @node Drum rolls
@@ -140,7 +160,8 @@ overridden to achieve a pleasing baseline.
 
 
 @seealso
-Snippets: @rlsr{Percussion}.
+Snippets:
+@rlsr{Percussion}.
 
 
 @node Pitched percussion
@@ -155,9 +176,11 @@ This is covered in other sections of the manual.
 @c TODO: possibly link to an alternate section of NR 3.5, if
 @c "percussion in MIDI" gets a separate subsubsection for
 @c pitched percussion sounds.  -gp
-Notation Reference: @ref{Percussion in MIDI}.
+Notation Reference:
+@ref{Percussion in MIDI}.
 
-Snippets: @rlsr{Percussion}.
+Snippets:
+@rlsr{Percussion}.
 
 
 @node Percussion staves
@@ -186,13 +209,11 @@ down = \drummode {
 
 The above example shows verbose polyphonic notation.  The short
 polyphonic notation, described in @rlearning{I'm hearing Voices},
-can also be used if the voices are instantiated by hand first.
+can also be used.
 For example,
 
 @lilypond[quote,verbatim]
 \new DrumStaff <<
-  \new DrumVoice = "1" { s1*2 }
-  \new DrumVoice = "2" { s1*2 }
   \drummode {
     bd4 sn4 bd4 sn4
     << {
@@ -357,12 +378,13 @@ own list at the top of your file.
 
 @lilypond[quote,verbatim]
 #(define mydrums '(
-         (bassdrum     default   #f         -1)
-         (snare        default   #f         0)
-         (hihat        cross     #f         1)
-         (pedalhihat   xcircle   "stopped"  2)
-         (lowtom       diamond   #f         3)))
-up = \drummode { hh8 hh hh hh hhp4 hhp }
+         (bassdrum        default   #f           -1)
+         (snare           default   #f           0)
+         (hihat           cross     #f           1)
+         (halfopenhihat   cross     "halfopen"   1)
+         (pedalhihat      xcircle   "stopped"    2)
+         (lowtom          diamond   #f           3)))
+up = \drummode { hh8 hh hhho hhho hhp4 hhp }
 down = \drummode { bd4 sn bd toml8 toml }
 
 \new DrumStaff <<
@@ -487,7 +509,7 @@ bellstaff = {
 }
 @end lilypond
 
-Here an short example by maestro Stravinsky (from @q{L'histoire du Soldat})
+Here a short example taken from Stravinsky's @q{L'histoire du Soldat}.
 
 @lilypond[quote,verbatim]
 #(define mydrums '((bassdrum   default #t  4)
@@ -550,9 +572,12 @@ drumsB = {
 
 
 @seealso
-Snippets: @rlsr{Percussion}.
+Snippets:
+@rlsr{Percussion}.
 
-Internals Reference: @rinternals{DrumStaff}, @rinternals{DrumVoice}.
+Internals Reference:
+@rinternals{DrumStaff},
+@rinternals{DrumVoice}.
 
 
 @c TODO: check name -gp
@@ -592,4 +617,5 @@ around each @code{\parenthesize} statement.
 
 
 @seealso
-Snippets: @rlsr{Percussion}.
+Snippets:
+@rlsr{Percussion}.