Re: Organ template in fundamental.itely is incomplete

[Werner LEMBERG]

> The organ template given in `fundamental.itely' lacks an important
> property, namely the limited stretchability of the pedal staff.
> Without this, the distance of the pedal staff w.r.t. the other two
> staves can become far too big.

Here's a documentation patch.


    Werner


======================================================================


--- fundamental.itely.old       2010-05-15 16:16:53.000000000 +0200
+++ fundamental.itely   2010-07-11 19:33:13.000000000 +0200
@@ -2819,6 +2819,70 @@
 @}  % end Score context
 @end example
 
+The above layout of the organ staves is almost perfect; however,
+there is a slight defect which is not visible by looking at just a
+single system: The distance of the pedal staff to the left hand staff
+should behave approximately the same as the right hand staff to the
+left hand staff.  In particular, the stretchability of staves in a
address@hidden context is limited (so that the distance between
+the staves for the left and right hand can't become too large), and
+the pedal staff should behave similarly.
+
+Stretchability of staves can be controlled with the
address@hidden property of the @code{VerticalAxisGroup}
address@hidden object} (commonly called @q{grob}s within the lilypond
+documentation) -- don't worry about the details right now; this is
+fully explained later.  For the curious, have a look at
address@hidden of modifying properties}.  Currently, it is not
+possible to modify the @code{stretchability} sub-property only, we
+thus have to copy the other sub-properties also.  Again, for the
+curious, you can find the default values in file
address@hidden/@/define-grobs@/.scm} by looking up the definition of the
address@hidden grob.  The value for @code{stretchability}
+is taken from the definition of the @code{PianoStaff} context (in
+file @file{ly/@/engraver-init@/.ly}) so that the values are
+identical.
+
address@hidden
+\score @{
+  <<  % PianoStaff and Pedal Staff must be simultaneous
+    \new PianoStaff <<
+      \new Staff = "ManualOne" <<
+        \keyTime  % set key and time signature
+        \clef "treble"
+        \new Voice @{
+          \voiceOne
+          \ManualOneVoiceOneMusic
+        @}
+        \new Voice @{
+          \voiceTwo
+          \ManualOneVoiceTwoMusic
+        @}
+      >>  % end ManualOne Staff context
+      \new Staff = "ManualTwo" \with @{
+        \override VerticalAxisGroup
+          #'next-staff-spacing = #'((space . 9)
+                                    (minimum-distance . 8)
+                                    (padding . 1)
+                                    (stretchability . 5))
+      @} <<
+        \keyTime
+        \clef "bass"
+        \new Voice @{
+          \ManualTwoMusic
+        @}
+      >>  % end ManualTwo Staff context
+    >>  % end PianoStaff context
+    \new Staff = "PedalOrgan" <<
+      \keyTime
+      \clef "bass"
+      \new Voice @{
+        \PedalOrganMusic
+      @}
+    >>  % end PedalOrgan Staff
+  >>
address@hidden  % end Score context
address@hidden example
 That completes the structure.  Any three-staff organ music
 will have a similar structure, although the number of voices
 may vary.  All that remains now
@@ -2862,7 +2926,13 @@
           \ManualOneVoiceTwoMusic
         }
       >>  % end ManualOne Staff context
-      \new Staff = "ManualTwo" <<
+      \new Staff = "ManualTwo" \with {
+        \override VerticalAxisGroup
+          #'next-staff-spacing = #'((space . 9)
+                                    (minimum-distance . 8)
+                                    (padding . 1)
+                                    (stretchability . 5))
+      } <<
         \keyTime
         \clef "bass"
         \new Voice {