From d0ac9b20bd556164604b52e79e90ad5e4b3cf83b Mon Sep 17 00:00:00 2001
From: Keith OHara <k-ohara5a5a@oco.net>
Date: Tue, 17 Dec 2013 14:58:29 -0800
Subject: [PATCH] spacing-options: clarify documentation

---
 Documentation/notation/spacing.itely |  3 +--
 lily/spacing-options.cc              | 11 ++++-------
 scm/define-grob-properties.scm       | 13 ++++++-------
 3 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 23d7cf05c5..1ce8ec5c13 100644
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -2768,8 +2768,7 @@ more space, shorter durations get less.  The shortest durations get a
 fixed amount of space (which is controlled by
 @code{shortest-duration-space} in the @rinternals{SpacingSpanner}
 object).  The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
+duration adds @code{spacing-increment} of space to the note.
 
 For example, the following piece contains lots of half, quarter, and
 8th notes; the eighth note is followed by 1 note head width (NHW).
diff --git a/lily/spacing-options.cc b/lily/spacing-options.cc
index e90dcebcab..7641581c35 100644
--- a/lily/spacing-options.cc
+++ b/lily/spacing-options.cc
@@ -66,9 +66,9 @@ Spacing_options::Spacing_options ()
 Real
 Spacing_options::get_duration_space (Rational d) const
 {
-  Real k = shortest_duration_space_;
+  Real ratio = d / global_shortest_;
 
-  if (d < global_shortest_)
+  if (ratio < 1.0)
     {
       /*
         We don't space really short notes using the log of the
@@ -86,9 +86,8 @@ Spacing_options::get_duration_space (Rational d) const
 
 
       */
-      Rational ratio = d / global_shortest_;
 
-      return ((k - 1) + double (ratio)) * increment_;
+      return (shortest_duration_space_ + ratio - 1) * increment_;
     }
   else
     {
@@ -97,10 +96,8 @@ Spacing_options::get_duration_space (Rational d) const
         Report OSU-CISRC-10/87-TR35, Department of Computer and
         Information Science, The Ohio State University, 1987.
       */
-      Real log = log_2 (global_shortest_);
-      k -= log;
 
-      return (log_2 (d) + k) * increment_;
+      return (shortest_duration_space_ + log_2 (ratio)) * increment_;
     }
 }
 
diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index cfa2cfb4c1..6e7e8ad955 100644
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -802,9 +802,8 @@ ending at that staff-position.")
      (shorten-pair ,number-pair? "The lengths to shorten a
 text-spanner on both sides, for example a pedal bracket.  Positive
 values shorten the text-spanner, while negative values lengthen it.")
-     (shortest-duration-space ,ly:dimension? "Start with this much
-space for the shortest duration.  This is expressed in
-@code{spacing-increment} as unit.  See also
+     (shortest-duration-space ,number? "Start with this multiple of
+@code{spacing-increment} space for the shortest duration.  See also
 @rinternals{spacing-spanner-interface}.")
      (shortest-playing-duration ,ly:moment? "The duration of the
 shortest note playing here.")
@@ -849,8 +848,8 @@ instead of to the beginning of the non-musical column.  If there is a
 clef change followed by a bar line, for example, this means that we
 will try to space the non-musical column as though the clef is not
 there.")
-     (spacing-increment ,number? "Add this much space for a doubled
-duration.  Typically, the width of a note head.  See also
+     (spacing-increment ,ly:dimension? "The unit of length for
+note-spacing.  Typically, the width of a note head.  See also
 @rinternals{spacing-spanner-interface}.")
      (spacing-pair ,pair? "A pair of alignment symbols which set an object's
 spacing relative to its left and right @code{BreakAlignment}s.
@@ -986,8 +985,8 @@ possible.")
 ;;; u
 ;;;
      (uniform-stretching ,boolean? "If set, items stretch
-proportionally to their durations.  This looks better in complex
-polyphonic patterns.")
+proportionally to their natural separation based on durations.
+This looks better in complex polyphonic patterns.")
      (used ,boolean? "If set, this spacing column is kept in the
 spacing problem.")
      (usable-duration-logs ,list? "List of @code{duration-log}s that
-- 
2.39.2