diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 658fc62..155d898 100644
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -29,6 +29,7 @@ or stretched.
 * Horizontal spacing::          
 * Breaks::                      
 * Displaying spacing::          
+* Skyline vertical placement::  
 @end menu
 
 
@@ -1186,3 +1187,69 @@ (@var{a},@var{b}) are intervals, where @
 @var{b} the upper edge of the interval.
 
 
address@hidden Skyline vertical placement
address@hidden Skyline vertical placement
+
address@hidden outside-staff-priority
address@hidden outside-staff-padding
address@hidden outside-staff-horizontal-padding
+
+Intuitively, there are some objects in musical notation that belong
+to the staff and there are other objects that should be placed outside
+the staff. Objects belonging outside the staff include things such as
+rehearsal marks, text and dynamic markings (from now on, these will
+be called outside-staff objects). LilyPond's rule for the
+vertical placement of outside-staff objects is to place them as close
+to the staff as possible but not so close that they collide with
+another object.
+
+LilyPond uses the outside-staff-priority property to determine
+whether a grob is an outside-staff object: if outside-staff-priority
+is a number, the grob is an outside-staff object. In addition, the
+outside-staff-priority tells LilyPond in which order the objects
+should be placed.
+
+First, LilyPond places all the objects that do not belong outside
+the staff. The it sorts the outside-staff objects according to their
+outside-staff priority (in increasing order). One by one, LilyPond
+takes the outside-staff objects and places them so that they do
+not collide with any objects that have already been placed. That
+is, if two outside-staff grobs are competing for the same space, the one
+with the lower outside-staff-priority will be placed closer to the staff.
+
address@hidden,ragged-right,relative=2,fragment,verbatim]
+c4_"Text"\pp
+r2.
+\once \override TextScript #'outside-staff-priority = #1
+c4_"Text"\pp % this time the text will be closer to the staff
+r2.
address@hidden lilypond
+
+The vertical padding between an outside-staff object and the
+previously-positioned grobs can be controlled with outside-staff-padding.
+
address@hidden,ragged-right,relative=2,fragment,verbatim]
+\once \override TextScript #'outside-staff-padding = #0
+a'^"This text is placed very close to the note"
+\once \override TextScript #'outside-staff-padding = #3
+c^"This text is padded away from the previous text"
+c^"This text is placed close to the previous text"
address@hidden lilypond
+
+By default, outside-staff objects are placed without regard to
+their horizontal distance from the previously-posititioned grobs. This
+can lead to situations in which objects are placed very close to each
+other horizontally. Setting the outside-staff-horizontal-padding property
+causes an object to be positioned high enough so that such a situation
+doesn't occur.
+
address@hidden,ragged-right,relative=2,fragment,verbatim]
+% the markup is too close to the following note
+c2^"Text"
+c''2
+% setting outside-staff-horizontal-padding fixes this
+R1
+\once \override TextScript #'outside-staff-horizontal-padding = #1
+c,,2^"Text"
+c''2
address@hidden lilypond