X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fkeyboards.itely;h=d9c12777e8de58c8c5ad2072024d1403ac144217;hb=9dd913c87e4b2616c45f753a265fe53972a93868;hp=7adae697efd910af2b3bc385e28d36b644661358;hpb=445a429716d4a19b8437ec70597851d8ca60ee05;p=lilypond.git

diff --git a/Documentation/user/keyboards.itely b/Documentation/user/keyboards.itely
index 7adae697ef..d9c12777e8 100644
--- a/Documentation/user/keyboards.itely
+++ b/Documentation/user/keyboards.itely
@@ -8,18 +8,14 @@
 
 @c \version "2.11.38"
 
-@c Andrew's TODO List
-@c references - first pass complete
-@c manual changes - first pass complete
-@c automatic changes - first pass complete
-@c staff-change lines - first pass complete
-@c cross-staff stems - first pass complete
-@c pedals - first pass complete
-@c accordian discant symbols
-
 @node Keyboard instruments
 @section Keyboard instruments
 
+@lilypondfile[quote]{keyboard-headword.ly}
+
+This section discusses several aspects of music notation that are unique
+to keyboard instruments.
+
 @menu
 * Common notation for keyboards::
 * Piano::
@@ -29,6 +25,9 @@
 @node Common notation for keyboards
 @subsection Common notation for keyboards
 
+This section discusses notation issues that may arise for most keyboard
+instruments.
+
 @menu
 * References for keyboards::
 * Changing staff manually::
@@ -85,10 +84,6 @@ 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}
-
 @seealso
 
 Learning Manual:
@@ -114,10 +109,11 @@ Snippets:
 
 @knownissues
 
-Dynamics are not centered, but workarounds do exist.  See the
-@q{piano centered dynamics} template in @rlearning{Piano templates}.
-
-@c TODO Find out status of the dynamics engravers
+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 increase the
+@code{staff-padding} of dynamics as discussed in @rlearning{Moving
+objects}.
 
 @node Changing staff manually
 @subsubsection Changing staff manually
@@ -176,8 +172,8 @@ Learning Manual:
 @rlearning{Fixing overlapping notation}.
 
 Notation Reference:
-@ref{Stems},
-@ref{Automatic beams}.
+@ruser{Stems},
+@ruser{Automatic beams}.
 
 Snippets:
 @rlsr{Keyboards}.
@@ -261,9 +257,8 @@ Internals Reference:
 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.
-
+Chords will not be split across the staves; they will be assigned to a
+staff based on the first note named in the chord construct.
 
 @node Staff-change lines
 @subsubsection Staff-change lines
@@ -339,9 +334,8 @@ staff, or vice versa.
 @end lilypond
 
 @snippets
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-@c {indicating-cross-staff-chords-with-arpeggio-bracket.ly}
-
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{indicating-cross-staff-chords-with-arpeggio-bracket.ly}
 
 @seealso
 
@@ -354,95 +348,108 @@ Internals Reference:
 @node Piano
 @subsection Piano
 
+This section discusses notation issues that relate most directly to the
+piano.
+
 @menu
 * Piano pedals::
 @end menu
 
 @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
-
-@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
-@rinternals{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
+@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.
 
 @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 "|."
+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
 
-A third style of pedal notation is a mixture of text and brackets,
-obtained by setting the @code{pedalSustainStyle} property to
-@code{mixed}
+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]
+c4\sustainDown g c2\sustainUp
 \set Staff.pedalSustainStyle = #'mixed
-c\sustainDown d e
-b\sustainUp\sustainDown
-b g \sustainUp a \sustainDown \bar "|."
-@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.
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c\sostenutoDown d e c, f g a\sostenutoUp
+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
-@rinternals{PianoPedalBracket} in the Internals Reference) can be
-modified.  For example, the bracket may be extended to the right edge
-of the note head
-
-@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
+The placement of the pedal commands matches the physical movement of the
+sustain pedal during piano performance.  Pedalling to the final bar line
+is indicated by omitting the final pedal up command.
 
-@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
 
+This section discusses notation that is unique to the accordion.
+
 @menu
 * Discant symbols::
 @end menu
 
 @node Discant symbols
 @subsubsection Discant symbols
+@cindex accordion discant symbols
+@cindex discant symbols, accordion
+@cindex accordion shifts
+
+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 accordion maker has different names for the @notation{shifts} that
+select the various reed combinations, such as @notation{oboe},
+@notation{musette}, or @notation{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 This snippet should work once it's been tagged for the docs.
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@c {accordion-discant-symbols.ly}
+
+@seealso
+
+Snippets:
+@rlsr{Keyboards}.