From: Mark Polesky <markpolesky@yahoo.com>
Date: Fri, 11 Jul 2014 06:33:17 +0000 (-0700)
Subject: Issue 3996: Clarify 'thickness and 'line-thickness property docstrings.
X-Git-Tag: release/2.19.10-1~4
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=4726764cb591f622e7893407db0e7d42bcde90d9;p=lilypond.git

Issue 3996: Clarify 'thickness and 'line-thickness property docstrings.
---

diff --git a/lily/staff-symbol-referencer-scheme.cc b/lily/staff-symbol-referencer-scheme.cc
index f8028e424a..f72605fc26 100644
--- a/lily/staff-symbol-referencer-scheme.cc
+++ b/lily/staff-symbol-referencer-scheme.cc
@@ -52,8 +52,9 @@ LY_DEFINE (ly_position_on_line_p, "ly:position-on-line?",
 
 LY_DEFINE (ly_staff_symbol_line_thickness, "ly:staff-symbol-line-thickness",
            1, 0, 0, (SCM grob),
-           "Returns the @code{line-thickness} of the staff associated"
-           " with @var{grob}.")
+           "Returns the current staff-line thickness in the staff"
+           " associated with @var{grob}, expressed as a multiple of the"
+           " current staff-space height.")
 {
   LY_ASSERT_SMOB (Grob, grob, 1);
   Grob *g = unsmob_grob (grob);
@@ -63,8 +64,10 @@ LY_DEFINE (ly_staff_symbol_line_thickness, "ly:staff-symbol-line-thickness",
 
 LY_DEFINE (ly_staff_symbol_staff_space, "ly:staff-symbol-staff-space",
            1, 0, 0, (SCM grob),
-           "Returns the @code{staff-space} of the staff associated"
-           " with @var{grob}.")
+           "Returns the current staff-space height in the staff"
+           " associated with @var{grob}, expressed as a multiple of the"
+           " default height of a staff-space in the traditional"
+           " five-line staff.")
 {
   LY_ASSERT_SMOB (Grob, grob, 1);
   Grob *g = unsmob_grob (grob);
diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index fbb9d679ac..05e6921784 100644
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -458,7 +458,9 @@ etc. are already taken.")
 ;;; h
 ;;;
      (hair-thickness ,number? "Thickness of the thin line in a bar
-line.")
+line, expressed as a multiple of the default staff-line thickness
+(i.e. the visual output is @emph{not} influenced by changes to
+@code{@var{Staff}.StaffSymbol.thickness}).")
      (harp-pedal-details ,list? "An alist of detailed grob properties
 for harp pedal diagrams.  Each alist entry consists of a
 @code{(@var{property} . @var{value})} pair.  The properties which can
@@ -531,8 +533,10 @@ slur quants to this position, and print the respective scores.")
 ;;;
      (keep-inside-line ,boolean? "If set, this column cannot have
 objects sticking into the margin.")
-     (kern ,ly:dimension? "Amount of extra white space to add.  For
-bar lines, this is the amount of space after a thick line.")
+     (kern ,ly:dimension? "The space between bar lines in any type
+of double bar, expressed as a multiple of the default staff-line
+thickness (i.e. the visual output is @emph{not} influenced by
+changes to @code{@var{Staff}.StaffSymbol.thickness}).")
      (knee ,boolean? "Is this beam kneed?")
      (knee-spacing-correction ,number? "Factor for the optical
 correction amount for kneed beams.  Set between @code{0} for no
@@ -577,8 +581,12 @@ whether to put a line break at this column.  Can be @code{force} or
 if this column is the start of a system.")
      (line-count ,integer? "The number of staff lines.")
      (line-positions ,list? "Vertical positions of staff lines.")
-     (line-thickness ,number? "The thickness of the tie or slur
-contour.")
+     (line-thickness ,number? "For slurs and ties, this is the
+diameter of the virtual @qq{pen} that draws the two arcs of the
+curve's outline, which intersect at the endpoints.  This property
+is expressed as a multiple of the current staff-line thickness
+(i.e. the visual output is influenced by changes to
+@code{@var{Staff}.StaffSymbol.thickness}).")
      (long-text ,markup? "Text markup.  See @ruser{Formatting text}.")
 
 
@@ -965,10 +973,17 @@ this property.")
      (text-direction ,ly:dir? "This controls the ordering of the
 words.  The default @code{RIGHT} is for roman text.  Arabic or Hebrew
 should use @code{LEFT}.")
-     (thick-thickness ,number? "Bar line thickness, measured in
-@code{line-thickness}.")
-     (thickness ,number? "Line thickness, generally measured in
-@code{line-thickness}.")
+     (thick-thickness ,number? "Thickness of the thick line in a
+bar line, expressed as a multiple of the default staff-line
+thickness (i.e. the visual output is @emph{not} influenced by
+changes to @code{@var{Staff}.StaffSymbol.thickness}).")
+     (thickness ,number? "For grobs made up of lines, this is the
+thickness of the line.  For slurs and ties, this is the distance
+between the two arcs of the curve's outline at its thickest point,
+not counting the diameter of the virtual @qq{pen} that draws the
+arcs.  This property is expressed as a multiple of the current
+staff-line thickness (i.e. the visual output is influenced by
+changes to @code{@var{Staff}.StaffSymbol.thickness}).")
      (thin-kern ,number? "The space after a hair-line in a bar line.")
      (tie-configuration ,list? "List of @code{(@var{position} .
 @var{dir})} pairs, indicating the desired tie configuration, where