+As a rule, LilyPond's vertical spacing of musical objects is pretty
+good. Let's see how it does with a simple song, with 2 voices and
+piano accompaniment:
+
+@lilypond[quote,fragment,ragged-right]
+<<
+ \new ChoirStaff
+ <<
+ \new Staff {
+ \new Voice = "music" {
+ b'2 c' c' c'
+ }
+ }
+ \new Lyrics
+ \lyricsto "music" {
+ Here are some lyrics
+ }
+ \new Staff {
+ \clef bass e'2 f e c
+ }
+ >>
+ \new PianoStaff
+ <<
+ \new Staff {
+ g''2 c'' c'' a''
+ }
+ \new Staff {
+ \clef bass e2 f c e
+ }
+ >>
+>>
+@end lilypond
+
+There's nothing wrong with the default vertical spacing. However, let's
+assume that you're working with a publisher with some specific
+requirements for vertical spacing of staves and lyrics: they want
+the lyrics spaced away from any notes, they want the piano
+accompaniment spaced away from the vocal line and they want the two
+piano staves pushed together tightly. Let's start with the lyrics.
+
+Lyrics sit within a system, and therefore the commands to space them
+are found in @ruser{Flexible vertical spacing within systems}. It
+tells us that lyrics are @code{non-staff lines} and therefore the
+command to change their spacing will refer to the @code{nonstaff}
+property. Spacing them away from the staff to which they relate
+(the top line) will use the @code{relatedstaff} property. Spacing
+them from the lower line will use the @code{unrelatedstaff} property.
+The vocal parts are part of a @code{VerticalAxisGroup}, so we need to
+adjust its properties. Let's try it and see if it works.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+ \new ChoirStaff
+ <<
+ \new Staff {
+ \new Voice = "music" {
+ b'2 c' c' c'
+ }
+ }
+ \new Lyrics \with {
+ \override VerticalAxisGroup.
+ nonstaff-relatedstaff-spacing.padding = #5
+ \override VerticalAxisGroup.
+ nonstaff-unrelatedstaff-spacing.padding = #5
+ }
+ \lyricsto "music" {
+ Here are some lyrics
+ }
+ \new Staff {
+ \clef bass e'2 f e c
+ }
+ >>
+ \new PianoStaff
+ <<
+ \new Staff {
+ g''2 c'' c'' a''
+ }
+ \new Staff {
+ \clef bass e2 f c e
+ }
+ >>
+>>
+@end lilypond
+
+Well - yes it does, but perhaps too well. When we set the
+@code{padding} to 5, LilyPond adds 5 staff spaces to the distance
+between objects, which is too much for us here. We'll use 2.
+
+Next, let's move the piano music away from the vocal parts. The
+vocal music is a @code{ChoirStaff}, so we need to increase the
+spacing between that group of staves and the piano staff below.
+We'll do this by changing the @code{basic-distance} of the
+@code{StaffGrouper}'s @code{staffgroup-staff-spacing}.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+ \new ChoirStaff \with {
+ \override StaffGrouper.
+ staffgroup-staff-spacing.basic-distance = #15
+ }
+ <<
+ \new Staff {
+ \new Voice = "music" {
+ b'2 c' c' c'
+ }
+ }
+ \new Lyrics \with {
+ \override VerticalAxisGroup.
+ nonstaff-relatedstaff-spacing.padding = #2
+ \override VerticalAxisGroup.
+ nonstaff-unrelatedstaff-spacing.padding = #2
+ }
+ \lyricsto "music" {
+ Here are some lyrics
+ }
+ \new Staff {
+ \clef bass e'2 f e c
+ }
+ >>
+ \new PianoStaff
+ <<
+ \new Staff {
+ g''2 c'' c'' a''
+ }
+ \new Staff {
+ \clef bass e2 f c e
+ }
+ >>
+>>
+@end lilypond
+
+Excellent. Now just for the last requirement to make the piano staves
+closer together. To do this, we again alter the properties of the
+@code{StaffGrouper}, but this time we're going to reduce both
+the @code{basic-distance} and the @code{padding}. We can do this
+as shown below.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+ \new ChoirStaff \with {
+ \override StaffGrouper.
+ staffgroup-staff-spacing.basic-distance = #15
+ }
+ <<
+ \new Staff {
+ \new Voice = "music" {
+ b'2 c' c' c'
+ }
+ }
+ \new Lyrics \with {
+ \override VerticalAxisGroup.
+ nonstaff-relatedstaff-spacing.padding = #2
+ \override VerticalAxisGroup.
+ nonstaff-unrelatedstaff-spacing.padding = #2
+ }
+ \lyricsto "music" {
+ Here are some lyrics
+ }
+ \new Staff {
+ \clef bass e'2 f e c
+ }
+ >>
+ \new PianoStaff \with {
+ \override StaffGrouper.staff-staff-spacing = #'(
+ (basic-distance . 0)
+ (padding . 0))
+ }
+ <<
+ \new Staff {
+ g''2 c'' c'' a''
+ }
+ \new Staff {
+ \clef bass e2 f c e
+ }
+ >>
+>>
+@end lilypond
+
+That's put them really close together -- but it's what
+the publisher wanted. They could be moved further
+apart by altering the @code{padding} or @code{basic-distance}
+if wanted.
+
+There are many ways of altering vertical spacing. A key point
+to remember is that the spacing between objects in a
+@code{StaffGroup} (like @code{GrandStaff} or
+@code{PianoStaff} groups) is controlled by the spacing variables
+of the @code{StaffGrouper}. Spacing from ungrouped staves
+(like @code{Lyrics} and @code{Staff}) is controlled by the
+variables of the @code{VerticalAxisGroup}. See the
+@ruser{Flexible vertical spacing paper variables} and
+@ruser{Flexible vertical spacing within systems} for more
+details.