X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fkeyboards.itely;h=f0e6833b05f40e2e04b608d45b0d2d53f010b1aa;hb=30e1840bcc05a2d51f0742b0235a47bf0ef66f86;hp=f84c25e782228af5f5a1637e960ad10dc11c2417;hpb=48bf29cfe7e13b2cb61c51a276305472ec84c08b;p=lilypond.git

diff --git a/Documentation/user/keyboards.itely b/Documentation/user/keyboards.itely
index f84c25e782..f0e6833b05 100644
--- a/Documentation/user/keyboards.itely
+++ b/Documentation/user/keyboards.itely
@@ -8,19 +8,15 @@
 
 @c \version "2.11.38"
 
-@c Andrew's TODO List
-@c references - started
-@c piano staff - started
-@c manual changes - started
-@c automatic changes
-@c staff-chagne lines
-@c cross-staff stems
-@c pedals
-@c discant symbols
+@c "I have finished the first draft." -AH
 
 @node Keyboard instruments
 @section Keyboard instruments
 
+@lilypondfile[quote]{keyboard-headword.ly}
+
+FIXME add sentence
+
 @menu
 * Common notation for keyboards::
 * Piano::
@@ -30,9 +26,10 @@
 @node Common notation for keyboards
 @subsection Common notation for keyboards
 
+FIXME add sentence
+
 @menu
 * References for keyboards::
-* The piano staff::
 * Changing staff manually::
 * Changing staff automatically::
 * Staff-change lines::
@@ -42,24 +39,52 @@
 @node References for keyboards
 @subsubsection References for keyboards
 
-Keyboard music can be written in parallel with
+Keyboard instruments are usually notated with Piano staves.  These
+are two or more normal staves coupled with a brace.  The same
+notation is also used for harps and other keyed instruments.
+Organ music is normally written with two staves inside a
+@code{PianoStaff} group and third, normal staff for the pedals.
+
+The staves in keyboard music are largely independent, but
+sometimes voices can cross between the two staves.  In this
+section we discuss some notation techniques particular to keyboard
+music.
+
+Several common issues in keyboard music are covered elsewhere:
+
+@itemize
+@item Keyboard music usually contains multiple voices and the
+number of voices may change regularly; this is described in
+@ref{Collision resolution}.
+
+@item Keyboard music can be written in parallel, as described in
 @ref{Writing music in parallel}.
-Fingerings are indicated with @ref{Fingering instructions}.
-Organ pedal indications are inserted as articulations, see
+
+@item Fingerings are indicated with @ref{Fingering instructions}.
+
+@item Organ pedal indications are inserted as articulations, see
 @ref{List of articulations}.
-Vertical grid lines can be shown with @ref{Grid lines}.
-Keyboard music often contains @notation{Laissez vibrer} ties as well as
-ties on arpeggios and tremelos, described in @ref{Ties}.
-Arpeggios can be placed across multiple voices and staves with
-@ref{Arpeggio}.
-Tremelo marks are created with @ref{Tremolo repeats}.
-
-Several of the tweaks that can occur in keyboard music are
-demonstrated in @rlearning{Real music example}.  Hidden notes can
-be used to produce ties that cross voices, as shown
-@rlearning{Other uses for tweaks}.
 
-@snippets
+@item Vertical grid lines can be shown with @ref{Grid lines}.
+
+@item Keyboard music often contains @notation{Laissez vibrer} ties
+as well as ties on arpeggios and tremelos, described in
+@ref{Ties}.
+
+@item Placing arpeggios across multiple voices and staves is
+covered in @ref{Arpeggio}.
+
+@item Tremolo marks are described in @ref{Tremolo repeats}.
+
+@item Several of the tweaks that can occur in keyboard music are
+demonstrated in @rlearning{Real music example}.
+
+@item Hidden notes can be used to produce ties that cross voices,
+as shown in @rlearning{Other uses for tweaks}.
+
+@end itemize
+
+@c @snippets
 @c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
 @c {creating-slurs-across-voices.ly}
 
@@ -70,43 +95,29 @@ Learning Manual:
 @rlearning{Other uses for tweaks}.
 
 Notation Reference:
+@ref{Grouping staves},
+@ref{Instrument names},
 @ref{Writing music in parallel},
 @ref{Fingering instructions},
 @ref{Grid lines},
 @ref{Ties},
 @ref{Arpeggio},
-@ref{Tremolo repeats}.
-@ref{List of articulations}
-
-Snippets:
-@c @lsrdir{Keyboard instruments}.
-
-
-@node The piano staff
-@subsubsection The piano staff
-
-Keyboard instruments are usually notated with Piano staves.  These
-are two or more normal staves coupled with a brace.  The same
-notation is also used for harps and other key instruments.  Organ
-music is normally written with two staves inside a
-@internalsref{PianoStaff} group and third, normal staff for the
-pedals.
-
-The staves in keyboard music are largely independent, but sometimes
-voices can cross between the two staves.  In this section we discuss
-some notation techniques particular to keyboard music.
-
-@seealso
-Notation Reference:
-@ruser{Grouping staves},
-@ruser{Instrument Names}.
+@ref{Tremolo repeats},
+@ref{List of articulations}.
 
 Internals Reference:
-@internalsref{PianoStaff}.
+@rinternals{PianoStaff}.
+
+Snippets:
+@rlsr{Keyboards}.
 
 @knownissues
-Dynamics are not centered, but workarounds do exist.  See the
-@q{piano centered dynamics} template in @rlearning{Piano templates}.
+
+Dynamics are not automatically centered, but workarounds do exist.  One
+option is the @q{piano centered dynamics} template under
+@rlearning{Piano templates}; another option is to add dynamics
+normally and then increase their staff-paddingm as discussed in
+@rlearning{Moving objects}.
 
 @node Changing staff manually
 @subsubsection Changing staff manually
@@ -121,39 +132,46 @@ Dynamics are not centered, but workarounds do exist.  See the
 @funindex \change
 
 Voices can be switched between staves manually, using the command
+
 @example
 \change Staff = @var{staffname}
 @end example
 
 @noindent
-The string @var{staffname} is the name of the staff.  It switches the
-current voice from its current staff to the Staff called
-@var{staffname}.  Typical values for @var{staffname} are @code{"up"}
-and @code{"down"}, or @code{"RH"} and @code{"LH"}.
+The string @var{staffname} is the name of the staff.  It switches
+the current voice from its current staff to the Staff called
+@var{staffname}.  Typical values for @var{staffname} are
+@code{"up"} and @code{"down"}, or @code{"RH"} and @code{"LH"}.
 
 Cross-staff notes are beamed automatically:
 
 @lilypond[verbatim,quote,ragged-right]
-upStaff = \change Staff = up
-downStaff = \change Staff = down
 \new PianoStaff <<
   \new Staff = "up" {
-    <e' c'>8 \downStaff g fis g \upStaff
-    <g'' c''>8 \downStaff e dis e \upStaff
+    <e' c'>8
+    \change Staff = down
+    g fis g
+    \change Staff = up
+    <g'' c''>8
+    \change Staff = down
+    e dis e
+    \change Staff = up
   }
   \new Staff = "down" {
-    \clef "bass"
-    s1 % keep the context alive
+    \clef bass
+    s1 % keep staff alive
   }
 >>
 @end lilypond
 
 If the beaming needs to be tweaked, make any changes to the stem
-directions first. The beam positions are then measured from the center
-of the staff that is closest to the beam. For a simple example of beam
-tweaking, see @rlearning{Fixing overlapping notation}.
+directions first.  The beam positions are then measured from the
+center of the staff that is closest to the beam.  For a simple
+example of beam tweaking, see @rlearning{Fixing overlapping
+notation}.
 
 @seealso
+
 Learning Manual:
 @rlearning{Fixing overlapping notation}.
 
@@ -162,134 +180,176 @@ Notation Reference:
 @ruser{Automatic beams}.
 
 Snippets:
-@c @lsrdir{Keyboard instruments}.
+@rlsr{Keyboards}.
 
 Internals Reference:
-@internalsref{Beam}.
+@rinternals{Beam}.
+
 
 @node Changing staff automatically
 @subsubsection Changing staff automatically
+
+@cindex changing staff automatically
 @cindex automatic staff changes
 @cindex staff changes, automatic
+@funindex \autochange
 
-Voices can be made to switch automatically between the top and the bottom
-staff.  The syntax for this is
+Voices can be made to switch automatically between the top and the
+bottom staff.  The syntax for this is
 
-@quotation
 @example
 \autochange @dots{}@var{music}@dots{}
 @end example
-@end quotation
 
 @noindent
-This will create two staves inside the current PianoStaff, called
-@code{up} and @code{down}.  The lower staff will be in bass clef by
-default.
+This will create two staves inside the current staff group
+(usually a @code{PianoStaff}), called @code{"up"} and
+@code{"down"}.  The lower staff will be in bass clef by default.
+The autochanger switches on basis of the pitch (middle C is the
+turning point), and it looks ahead skipping over rests to switch
+in advance.
 
-A @code{\relative} section that is outside of @code{\autochange} has
-no effect on the pitches of @var{music}, so, if necessary, put
-@code{\relative} inside @code{\autochange} like
-
-@quotation
-@example
-\autochange \relative @dots{} @dots{}
-@end example
-@end quotation
+@lilypond[quote,verbatim,ragged-right]
+\new PianoStaff {
+  \autochange {
+    g4 a b c' d' r4 a g
+  }
+}
+@end lilypond
 
+A @code{\relative} section that is outside of @code{\autochange}
+has no effect on the pitches of the music, so if necessary, put
+@code{\relative} inside @code{\autochange}.
 
-The autochanger switches on basis of the pitch (middle C is the turning
-point), and it looks ahead skipping over rests to switch in
-advance.  Here is a practical example
+If additional control is needed over the individual staves, they
+can be created manually with the names @code{"up"} and
+@code{"down"}.  The @code{\autochange} command will then switch
+its voice between the existing staves.  For example, this is
+necessary to place a key signature in the lower staff:
 
 @lilypond[quote,verbatim,ragged-right]
-\new PianoStaff
-  \autochange \relative c'
-  {
-    g4 a b c d r4 a g
+\new PianoStaff <<
+  \new Staff = "up" {
+    \new Voice = "melOne" {
+      \key g \major
+      \autochange \relative c' {
+        g8 b a c b d c e
+        d r fis, g a2
+      }
+    }
+  }
+  \new Staff = "down" {
+    \key g \major
+    \clef bass
   }
+>>
 @end lilypond
 
-
 @seealso
 
-Notation Reference: @ref{Changing staff manually}.
-
-Internals Reference: @internalsref{AutoChangeMusic}.
+Notation Reference:
+@ref{Changing staff manually}.
 
+Snippets:
+@rlsr{Keyboards}.
 
+Internals Reference:
+@rinternals{AutoChangeMusic}.
 
 @knownissues
 
 The staff switches may not end up in optimal places.  For high
 quality output, staff switches should be specified manually.
 
+Chords will not be split across the staves; the staff will be
+chosen by the first note named in the chord.
 
-@code{\autochange} cannot be inside @code{\times}.
 
 @node Staff-change lines
 @subsubsection Staff-change lines
 
-
+@cindex staff-change lines
+@cindex cross-staff lines
+@cindex lines, staff-change follower
 @cindex follow voice
 @cindex staff switching
 @cindex cross-staff
-
 @funindex followVoice
 
-Whenever a voice switches to another staff, a line connecting the notes
-can be printed automatically.  This is switched on by setting
-@code{followVoice} to true
+Whenever a voice switches to another staff, a line connecting the
+notes can be printed automatically:
 
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
 \new PianoStaff <<
-  \new Staff="one" {
-    \set followVoice = ##t
+  \new Staff = "one" {
+    \showStaffSwitch
     c1
     \change Staff=two
     b2 a
   }
-  \new Staff="two" { \clef bass \skip 1*2 }
+  \new Staff = "two" { \clef bass s1*2 }
 >>
 @end lilypond
 
-@seealso
-
-Internals Reference: @internalsref{VoiceFollower}.
-
 @predefined
 
 @funindex \showStaffSwitch
-@code{\showStaffSwitch},
 @funindex \hideStaffSwitch
-@code{\hideStaffSwitch}.
+@code{\showStaffSwitch}, @code{\hideStaffSwitch}.
+
+@seealso
+
+Snippets:
+@rlsr{Keyboards}.
+
+Internals Reference:
+@rinternals{VoiceFollower}.
+
 
 @node Cross-staff stems
 @subsubsection Cross-staff stems
 
+@cindex cross-staff notes
+@cindex notes, cross-staff
+@cindex cross-staff stems
+@cindex stems, cross-staff
+
 Chords that cross staves may be produced by increasing the length
 of the stem in the lower staff, so it reaches the stem in the upper
 staff, or vice versa.
 
 @lilypond[ragged-right,verbatim,quote]
-stemExtend = {
-  \once \override Stem #'length = #10
-  \once \override Stem #'cross-staff = ##t
-}
-noFlag = \once \override Stem #'flag-style = #'no-flag
 \new PianoStaff <<
-  \new Staff {
-    \stemDown \stemExtend
-    f'4
-    \stemExtend \noFlag
-    f'8
+  \new Staff \relative c' {
+    f8 e4 d8 <f bes,>2
   }
-  \new Staff {
-    \clef bass
-    a4 a8
+  \new Staff \relative c' {
+    << {
+      \clef bass
+      \stemUp
+      \override Stem #'length = #12
+      \override Stem #'cross-staff = ##t
+      \override Stem #'flag-style = #'no-flag
+      a8 g4 f8
+    } \\
+    { f,2 d' }
+    >>
   }
 >>
 @end lilypond
 
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{indicating-cross-staff-chords-with-arpeggio-bracket.ly}
+
+@seealso
+
+Snippets:
+@rlsr{Keyboards}.
+
+Internals Reference:
+@rinternals{Stem}
+
 @node Piano
 @subsection Piano
 
@@ -299,89 +359,110 @@ noFlag = \once \override Stem #'flag-style = #'no-flag
 
 @node Piano pedals
 @subsubsection Piano pedals
-@cindex Pedals
-
-Pianos have pedals that alter the way sound is produced.  Generally, a
-piano has three pedals, sustain, una corda, and sostenuto.
-
-
-Piano pedal instruction can be expressed by attaching
-@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
-@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
-note or chord
+@cindex piano pedals
+@cindex pedals, piano
+@cindex sustain pedal
+@cindex sostenuto pedal
+@cindex una corde
+@cindex tre corde
+@funindex \sustainDown
+@funindex \sustainUp
+@funindex \sostenutoDown
+@funindex \sostenutoUp
+@funindex \unaCorda
+@funindex \treCorde
+
+Pianos generally have three pedals that alter the way sound is
+produced: @notation{sustain}, @notation{sostenuto}
+(@notation{sos.}), and @notation{una corde} (@notation{U.C.}).
+Sustain pedals are also found on vibraphones and celestas.
+
+FIXME: see policy for allowed lilypond[] options.
+(ie use [relative=2])
 
 @lilypond[quote,ragged-right,fragment,verbatim]
-c'4\sustainDown c'4\sustainUp
-@end lilypond
-
-What is printed can be modified by setting @code{pedal@var{X}Strings},
-where @var{X} is one of the pedal types: @code{Sustain},
-@code{Sostenuto} or @code{UnaCorda}.  Refer to
-@internalsref{SustainPedal} in the program reference for more
-information.
-
-Pedals can also be indicated by a sequence of brackets, by setting the
-@code{pedalSustainStyle} property to bracket objects
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\set Staff.pedalSustainStyle = #'bracket
-c\sustainDown d e
-b\sustainUp\sustainDown
-b g \sustainUp a \sustainDown \bar "|."
-@end lilypond
-
-A third style of pedal notation is a mixture of text and brackets,
-obtained by setting the @code{pedalSustainStyle} property to
-@code{mixed}
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\set Staff.pedalSustainStyle = #'mixed
-c\sustainDown d e
-b\sustainUp\sustainDown
-b g \sustainUp a \sustainDown \bar "|."
+\relative c' {
+  c4\sustainDown d e g
+  <c, f a>1\sustainUp
+  c4\sostenutoDown e g c,
+  <bes d f>1\sostenutoUp
+  c4\unaCorda d e g
+  <d fis a>1\treCorde
+}
 @end lilypond
 
-The default @q{*Ped.} style for sustain and damper pedals corresponds to
-style @code{#'text}.  The sostenuto pedal uses @code{mixed} style by
-default.
+There are three styles of pedal indications: text, bracket, and mixed.
+The sustain pedal and the una corda pedal use the text style by default
+while the sostenuto pedal uses mixed by default.
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c\sostenutoDown d e c, f g a\sostenutoUp
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c'' {
+  c4\sustainDown g c2\sustainUp
+  \set Staff.pedalSustainStyle = #'mixed
+  c4\sustainDown g c d
+  d\sustainUp\sustainDown g, c2\sustainUp
+  \set Staff.pedalSustainStyle = #'bracket
+  c4\sustainDown g c d
+  d\sustainUp\sustainDown g, c2
+  \bar "|."
+}
 @end lilypond
 
-For fine-tuning the appearance of a pedal bracket, the properties
-@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
-@code{PianoPedalBracket} objects (see
-@internalsref{PianoPedalBracket} in the Internals Reference) can be
-modified.  For example, the bracket may be extended to the right edge
-of the note head
+The placement of the pedal commands matches the physical movement of the
+sustain pedal during piano performance.  Pedalling to the final barline
+is indicated by omitting the final pedal up command.
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0)
-c\sostenutoDown d e c, f g a\sostenutoUp
-@end lilypond
-
-@noindent
-Note that overrides must be placed before the note at which the 
-pedal bracket starts.
+@seealso
 
-@c TODO Check relative positions of the sustain pedal and
-@c      dynamics are correct (they collided in 2.11.44).
-@c      Give example showing this.
+Notation Reference:
+@ref{Ties}.
 
-@seealso
+Snippets:
+@rlsr{Keyboards}.
 
-Notation Reference: @ref{Ties} (laissez vibrer).
+Internals Reference:
+@rinternals{SustainPedal},
+@rinternals{SustainPedalLineSpanner},
+@rinternals{SostenutoPedal},
+@rinternals{SostenutoPedalLineSpanner},
+@rinternals{UnaCordaPedal},
+@rinternals{UnaCordaPedalLineSpanner},
+@rinternals{PianoPedalBracket},
+@rinternals{Piano_pedal_engraver}.
 
 @node Accordion
 @subsection Accordion
 
+FIXME add sentence
+
 @menu
 * Discant symbols::
 @end menu
 
 @node Discant symbols
 @subsubsection Discant symbols
+@cindex accordion discant symbols
+@cindex discant symbols, accordion
+@cindex accordion shifts
+
+@c FIXME: use @notation, not @q.
+@c FIXME: you might want to submit some of these terms to the MG.
+@c    If so, send an email to Kurt about this.
+
+Accordions are often built with more than one set of reeds that may be
+in unison with, an octave above, or an octave below the written pitch.
+Each accordian maker has different names for the @q{shifts} that
+select the various reed combinations, such as @q{oboe}, @q{musette}, or
+@q{bandonium}, so a system of symbols has come into use to simplify
+the performance instructions.
 
-@c TODO Add text from -user and lsr 194
-TBC
+@snippets
+
+@c FIXME: invalid snippet name.  Check the GDP snippet list.
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@c {accordion-discant-symbols.ly}
+
+@seealso
+
+Snippets:
+@rlsr{Keyboards}.