From 4975ad00b0709879f241982bdbbd5f1d7dce5e55 Mon Sep 17 00:00:00 2001
From: fred <fred>
Date: Wed, 27 Mar 2002 00:01:31 +0000
Subject: [PATCH] lilypond-1.3.98

---
 CHANGES                   |  35 ++++-
 VERSION                   |   2 +-
 input/test/jazz-chords.ly |   4 +-
 input/test/markup.ly      |   4 +-
 lily/text-item.cc         |  22 ++-
 scm/chord-names.scm       |  11 +-
 scm/font.scm              |  42 +++---
 scm/interface.scm         | 309 ++++++++++++++++++++++++--------------
 scm/slur.scm              |   4 +-
 9 files changed, 279 insertions(+), 154 deletions(-)

diff --git a/CHANGES b/CHANGES
index 8c6ace17ad..374d366791 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,28 @@
-1.3.96.jcn10
-============
+1.3.98
+======
+
+* Backend documentation updates and related cleanups
+
+* Removed \property bracketCollapseHeight, systemStartDelimiterGlyph
+
+* Bugfix: instrument-name on grandstaffs, see
+input/test/instrument-name-grandstaff.ly
+
+* Bugfix for tie/staffline collision.
+
+* Bugfix: also send out end-repeat if there are no alternatives.
+
+* Small solo cello suite fixes.
+
+1.3.97.jcn1
+===========
+
+* Added some interface documentation.
+
+* Added raise and kern to markup.  This should make Chord names usable.
+
+1.3.97
+======
 
 * Made small fixes to basic properties: regression-test compiles.
 
@@ -41,9 +64,8 @@ inclusive) is now in Scheme.
 
 * Self-documenting backend using ly/generate-documentation.ly
 
-
-1.3.95.jcn5
-===========
+1.3.96
+======
 
 * Added friendly message for the clueless dvips user.
 
@@ -340,8 +362,6 @@ INCOMPATIBLE CHANGE)
 
 * added input/test/bagpipe.ly
 
-
-
 1.3.87
 ======
 
@@ -392,7 +412,6 @@ lists.
 
 * Separated definition and implementation of contexts (moved
 definition out of Translator_group into Translator_def)
- 
 
 * pmx2ly.py fixes: now handles text at beginning of block correctly.
 
diff --git a/VERSION b/VERSION
index 23c4d59326..4ec85b0d8c 100644
--- a/VERSION
+++ b/VERSION
@@ -1,7 +1,7 @@
 PACKAGE_NAME=LilyPond
 MAJOR_VERSION=1
 MINOR_VERSION=3
-PATCH_LEVEL=97
+PATCH_LEVEL=98
 MY_PATCH_LEVEL=
 
 # use the above to send patches: MY_PATCH_LEVEL is always empty for a
diff --git a/input/test/jazz-chords.ly b/input/test/jazz-chords.ly
index 44d35bc008..8bcafc2aea 100644
--- a/input/test/jazz-chords.ly
+++ b/input/test/jazz-chords.ly
@@ -16,11 +16,11 @@
 
 	 ;(((0 . 0) (2 . -1) (4 . -1) (6 . -2)) . (super "o7"))
 	 ;jazz: the delta, see jazz-chords.ly
-	 (((0 . 0) (2 . -1) (4 . -1) (6 . -2)) .  (super ((family . "math") "N")))
+	 (((0 . 0) (2 . -1) (4 . -1) (6 . -2)) .  (super ((font-family . "math") "N")))
+	 (((0 . 0) (2 . -1) (4 . -1) (6 . -1)) . (rows ((raise . 1) "o") ((raise . 0.5) ((kern . -0.5) ((font-size . "-3") "/"))) "7")) ; slashed o
 
 	 ;(((0 . 0) (2 . -1) (4 . -1) (6 . -1)) . (super "x7"))
 	 ; slashed o
-	 (((0 . 0) (2 . -1) (4 . -1) (6 . -1)) . (rows (super "o") ((kern . -0.5) ((size . "-3") "/")) "7"))
 	)
       chord::names-alist-american))
 
diff --git a/input/test/markup.ly b/input/test/markup.ly
index ccd03f18a9..9d7703fdf0 100644
--- a/input/test/markup.ly
+++ b/input/test/markup.ly
@@ -11,7 +11,7 @@
 
 		d-\textscript #'(lines "one" "two" "three")
 		e-\textscript #'(lines (bold "one") 
-		  (rows "and" "there" "is" ((family . "number") "2"))
+		  (rows "and" "there" "is" ((font-family . "number") "2"))
 		  (italic "three"))
 		f-\textscript #'(finger "3")
 		g-\textscript #'(music (named "noteheads-2"))
@@ -20,7 +20,7 @@
 		linewidth = -1.\mm;
 		\translator{
 			\ScoreContext
-			TextScript \push #'font-family = #'roman
+			TextScript \push #'font-family = #"roman"
 			TextScript \pop #'no-spacing-rods
 			TextScript \push #'direction = #1
 		}
diff --git a/lily/text-item.cc b/lily/text-item.cc
index 2d8f9bbe22..deada62d30 100644
--- a/lily/text-item.cc
+++ b/lily/text-item.cc
@@ -17,6 +17,7 @@
 #include "all-font-metrics.hh"
 #include "afm.hh"
 
+
 /*
   text: string | (markup sentence)
   markup: markup-symbol | (markup-symbol . parameter)
@@ -157,19 +158,36 @@ Text_item::markup_sentence2molecule (Score_element *me, SCM markup_sentence,
   SCM markup = gh_car (markup_sentence);
   SCM sentence = gh_cdr (markup_sentence);
   SCM f = get_elt_property (me, "markup-to-properties");
-  SCM p = gh_cons (gh_call1 (f, markup), properties);
+  SCM p = gh_append2 (gh_call1 (f, markup), properties);
 
   Axis align = X_AXIS;
   SCM a = scm_assoc (ly_symbol2scm ("align"), p);
   if (gh_pair_p (a) && gh_number_p (gh_cdr (a)))
     align = (Axis)gh_scm2int (gh_cdr (a));
 
+  Real staff_space = Staff_symbol_referencer::staff_space (me);
+  Real kern = 0;
+  SCM k = scm_assoc (ly_symbol2scm ("kern"), p);
+  if (gh_pair_p (k) && gh_number_p (gh_cdr (k)))
+    kern = gh_scm2double (gh_cdr (k)) * staff_space;
+			     
+  Real raise = 0;
+  SCM r = scm_assoc (ly_symbol2scm ("raise"), p);
+  if (gh_pair_p (r) && gh_number_p (gh_cdr (r)))
+    raise = gh_scm2double (gh_cdr (r)) * staff_space;
+
+  Offset o (align == X_AXIS ? kern : 0,
+	    (align == Y_AXIS ? - kern : 0) + raise);
+
   Molecule mol;
   while (gh_pair_p (sentence))
     {
       Molecule m = text2molecule (me, gh_car (sentence), p);
       if (!m.empty_b ())
-	mol.add_at_edge (align, align == X_AXIS ? RIGHT : DOWN, m, 0);
+	{
+	  m.translate (o);
+	  mol.add_at_edge (align, align == X_AXIS ? RIGHT : DOWN, m, 0);
+	}
       sentence = gh_cdr (sentence);
     }
   return mol;
diff --git a/scm/chord-names.scm b/scm/chord-names.scm
index 99400b03ab..a0cd520bf9 100644
--- a/scm/chord-names.scm
+++ b/scm/chord-names.scm
@@ -87,8 +87,9 @@
 	 (((0 . 0) (2 . 0) (4 . 0) (6 . -1)) . ("7"))
 	 (((0 . 0) (2 . -1) (4 . 0) (6 . 0)) . ("m(maj7)"))
 	 ;jazz: the delta, see jazz-chords.ly
-	 ;(((0 . 0) (2 . -1) (4 . -1) (6 . -2)) .  (super ((family . "math") "N"))
-	 (((0 . 0) (2 . -1) (4 . -1) (6 . -1)) . (rows (super "o") ((kern . -0.5) ((size . "-3") "/")) "7")) ; slashed o
+	 ;;(((0 . 0) (2 . -1) (4 . -1) (6 . -2)) .  (super ((font-family . "math") "N"))
+	 ;; slashed o
+	 (((0 . 0) (2 . -1) (4 . -1) (6 . -1)) . (rows ((raise . 1) "o") ((raise . 0.5) ((kern . -0.5) ((font-size . "-3") "/"))) "7")) ; slashed o
 	 (((0 . 0) (2 . 0) (4 . 1) (6 . -1)) . ("aug7"))
 	 (((0 . 0) (2 . 0) (4 . -1) (6 . 0)) . (rows "maj7" (music (named ("accidentals--1"))) "5"))
 	 (((0 . 0) (3 . 0) (4 . 0) (6 . -1)) . ("7sus4"))
@@ -120,8 +121,10 @@
 	       (list
 		(append '(named)
 			(list
-			 (string-append "accidentals-" 
-					(number->string (caddr pitch)))))))))))
+			  (append '((font-size . "-2"))
+				  (list
+				   (string-append "accidentals-" 
+						  (number->string (caddr pitch)))))))))))))
 
 
 (define (step->text pitch)
diff --git a/scm/font.scm b/scm/font.scm
index 1c641c854e..2f9a88fb45 100644
--- a/scm/font.scm
+++ b/scm/font.scm
@@ -98,38 +98,32 @@
 	      '(font-series font-shape font-family font-name font-point font-size)))))
     (font-regexp-to-font-name paper font-regexp)))
 
-(define markup-to-properties-alist
-  '(
-    (style . font-style)
-    (series . font-series)
-    (shape . font-shape)
-    (family . font-family)
-    (name . font-name)
-    (size . font-size)
-    (point . font-point)
-    (kern . kern)
-    ))
-    
 (define markup-abbrev-to-properties-alist
   (append
    '(
-     (rows . (align . 0))
-     (lines . (align . 1))
-     (roman . (font-family . "roman"))
-     (music . (font-family . "music"))
-     (bold . (font-series . "bold"))
-     (italic . (font-shape . "italic"))
-     (named . (lookup . name))
-     (text . (lookup . value))
-     ;; super needs some work
-     (super . (font-size . "-1")))
+     (rows . ((align . 0)))
+     (lines . ((align . 1)))
+     (roman . ((font-family . "roman")))
+     (music . ((font-family . "music")))
+     (bold . ((font-series . "bold")))
+     (italic . ((font-shape . "italic")))
+     (named . ((lookup . name)))
+     (super . ((raise . 1) (font-size . "-1")))
+     (sub . ((raise . -1) (font-size . "-1")))
+     (text . ((lookup . value)))
+     )
    (map (lambda (x) (cons (car x) (cons 'font-style (car x))))
 	style-to-font-alist)))
   
 (define (markup-to-properties markup)
+  ;;  (display "markup: `")
+  ;;(display markup)
+  ;;(display "'\n")
   (if (pair? markup)
-      (cons (cdr (assoc (car markup) markup-to-properties-alist)) (cdr markup))
-      (cdr (assoc markup markup-abbrev-to-properties-alist))))
+      (list markup)
+      (let ((entry (assoc markup markup-abbrev-to-properties-alist)))
+	(if entry (cdr entry)
+	    (list (cons markup #t))))))
 	
 (define (style-to-font-name paper style)
   (let* ((entry (assoc style style-to-font-alist))
diff --git a/scm/interface.scm b/scm/interface.scm
index d44e4cc729..e8d62d020b 100644
--- a/scm/interface.scm
+++ b/scm/interface.scm
@@ -43,21 +43,32 @@
   )))
 
 
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;;;;;;;;;;;;;;;
-;;;;;;;;;;;;;;;;;
-
 (define general-element-interface
   (lily-interface
    'general-element-interface
    "All elements support this"
-   (list (property-description 'X-offset-callbacks list? "")
-    (property-description 'Y-offset-callbacks list? "")
-    (property-description 'X-extent-callback procedure? "")
-    (property-description 'Y-extent-callback procedure? "")
+   (list
+    (property-description 'X-offset-callbacks list? "list of functions, each taking an element and axis argument. The function determine the position relative to this element's parent. The last one in the list is called first")
+    (property-description 'Y-offset-callbacks list? "see <code> X-offset-callbacks</code>")
+    (property-description 'X-extent-callback procedure? "procedure taking an element and axis argument, returning a number-pair. The return value is the extent of the element.")
+    (property-description 'Y-extent-callback procedure? "see <code> X-extent-callback </code>")
     (property-description 'font-size integer? "")
+    (property-description 'extra-offset number-pair? "pair of reals (a cons) forcing an extra offset   before outputting")
+    (property-description 'interfaces  list? "list of symbols indicating the interfaces supported by this object. Is initialized from the <code>meta</code> field.")
+    (property-description 'dependencies list? "list of score-element pointers that indicate who to compute first for certain global passes")
+    (property-description 'no-spacing-rods boolean? "read from elements: boolean that makes Separation_item ignore this item (MOVE ME TO ITEM)")
+    (property-description 'extra-extent-X number-pair? "enlarge in X dimension by this much, measured in staff space")
+    (property-description 'extra-extent-Y number-pair? "see <code>extra-extent-Y</code>")
+    (property-description 'minimum-extent-X number-pair? "minimum size in X dimension, measured in staff space")
+    (property-description 'minimum-extent-Y number-pair? "see <code>minimum-extent-Y</code>")
+    (property-description 'origin ly-input-location? "location in input file of the definition")
+    (property-description 'transparent boolean? "This is almost the
+same as setting molecule-callback to #f, but this retains the
+dimensions of this element, which means that you can erase elements
+individually. ")
+    (property-description 'molecule-callback procedure? "Function taking graphical element as argument, returning a Scheme encoded Molecule") 
     ))
-)
+  )
 
 (define beam-interface
   (lily-interface
@@ -114,7 +125,7 @@ more than this (in staffspace)")
    (list
     (property-description 'horizontal-shift integer? "integer that identifies ranking of note-column for horizontal shifting.")
     (property-description 'force-hshift number? "amount of collision_note_width that overides automatic collision settings.")
-    (property-description 'merge-differently-dotted boolean? "merge black noteheads with differing dot count.")
+    (property-description 'merge-differently-dotted boolean? "merge black noteheads with differing dot count in collisions.")
     ))
   )
 
@@ -123,17 +134,25 @@ more than this (in staffspace)")
    'stem-interface
    "A stem"
    (list
-    (property-description 'thickness number? "")
-    (property-description 'beamed-lengths list? "")
-    (property-description 'beamed-minimum-lengths list? "")
-    (property-description 'lengths list? "")
-    (property-description 'stem-shorten list? "")
-    (property-description 'default-neutral-direction dir? "")
-    (property-description 'direction dir? "")
-    (property-description 'stem-length number? "")
+    (property-description 'thickness number? "thickness, measured in stafflinethickness")
+    (property-description 'beamed-lengths list? "list of stem lengths given beam multiplicity ")
+    (property-description 'beamed-minimum-lengths list? "list of minimum stem lengths given beam multiplicity")
+    (property-description 'stem-centered boolean? "Center stems on note heads. Useful for mensural notation")
+    (property-description 'lengths list? "Stem length given multiplicity of flag")
+    (property-description 'beam ly-element? "pointer to the beam, if applicable")
+    (property-description 'stem-shorten list? "shorten stems in forced directions given flag multiplicity")
+    (property-description 'duration-log integer? "log of the duration, ie. 0=whole note, 1 = half note, etc.")
+    (property-description 'beaming number-pair? "number of beams extending to left and right")
+    (property-description 'default-neutral-direction dir? "Where to go if we're in the middle of the staff")
+    (property-description 'stem-end-position number? "Where does the stem end (the end is opposite to the support-head")
+    (property-description 'support-head ly-element? "the note head at
+one end of the stem")
+    (property-description 'heads list? "list of note heads")
+    (property-description 'direction dir? "up or down")
+    (property-description 'stem-length number? "length of stem")
     (property-description 'style string? "") ; symbol!?
     (property-description 'flag-style string? "") ; symbol!?
-    (property-description 'X-offset-callbacks list? "")
+    (property-description 'dir-forced boolean? "set if direction has been forced; read by Beam.")
     )))
 
 
@@ -146,12 +165,15 @@ more than this (in staffspace)")
     (property-description 'details list? "alist containing contaning a few magic constants.")
     (property-description 'attachment pair? "cons of symbols, '(LEFT-TYPE . RIGHT-TYPE), where both types may be alongside-stem, stem, head or loose-end")
     (property-description 'direction dir? "up or down?")
-    (property-description 'y-free number? "? ")
-    (property-description 'control-points list? "")
-    (property-description 'extremity-rules  list? "")
-    (property-description 'extremity-offset-alist list? "")
-    (property-description 'thickness list? "")
-    (property-description 'dash number? "number representing the length of the dashes.")
+   (property-description 'attachment-offset pair? "cons of offsets, '(LEFT-offset . RIGHT-offset).  This offset is added to the attachments to prevent ugly slurs.")
+     (property-description 'beautiful number? "number that dictates when a slur should be de-uglyfied.  It correlates with the enclosed area between noteheads and slurs.  A value of 0.1 yields only undisturbed slurs, a value of 5 will tolerate quite high blown slurs.")
+     (property-description 'y-free number? "minimal vertical gap between slur and noteheads or stems")
+     (property-description 'control-points list? "[internal] control points of bezier curve")
+     (property-description 'extremity-rules  list? "an alist (procedure slur dir) -> attachment to determine the attachment (see above).  If procedure returns #t, attachment is used.  Otherwise, the next procedure is tried.")
+     (property-description 'extremity-offset-alist list? "an alist (attachment stem-dir*dir slur-dir*dir) -> offset.  The offset adds to the centre of the notehead, or stem.")
+     (property-description 'thickness list? "The thickness[stafflinethickness] of slur in the centre.")
+     (property-description 'dashed number? "[FIXME: use dash-period/dash length; see text-spanner] number representing the length of the dashes.")
+
     )
    )
   )
@@ -159,8 +181,10 @@ more than this (in staffspace)")
 (define side-position-interface
   (lily-interface
    'side-position-interface
-   "put an element next to another one."
+   "Position a victim object (this one) next to other objects (the support)."
    (list
+   (property-description 'side-support list? "the support, a list of score elements")
+   (property-description 'direction-source ly-element? "in case side-relative-direction is set, which element  to get the direction from ")
     (property-description 'direction dir? "where to put the victim object (left or right?)")
     (property-description 'side-relative-direction dir? "if set: get the direction from a different object, and multiply by this.")
     (property-description 'minimum-space number? "minimum distance that the victim should move (after padding)")
@@ -181,6 +205,31 @@ more than this (in staffspace)")
     )
    ))
 
+(define line-of-score-interface
+  (lily-interface
+   'line-of-score-interface
+   "Super element, parent of all:
+<p>
+   The columns of a score that form one line.  The toplevel element.
+   Any element has a Line_of_score as both X and Y reference
+   point. The Paper_score contains one element of this type. Control
+   enters the Score_element dependency calculation from this single
+   Line_of_score object."
+   (list
+    (property-description 'between-system-string string? "string
+ to dump between two systems. Useful for forcing pagebreaks")
+    (property-description 'spacing-procedure procedure? "procedure taking
+graphical element as argument. This is called after before-line-breaking-callback, but before the actual line breaking itself.  Return value is ignored")
+    (property-description 'before-line-breaking-callback procedure?
+			  "Procedure taking graphical element as argument.
+This procedure is called (using dependency resolution) before line breaking, but after generating discretionary items. Return value is ignored")
+    (property-description 'after-line-breaking-callback procedure?
+			  "Procedure taking graphical element as argument.
+This procedure is called (using dependency resolution) after line breaking. Return value is ignored")
+    (property-description 'all-elements list? "list of all score elements in this line. Needed for protecting elements from GC.")
+    (property-description 'columns list? "list of all paper columns")
+    )))
+
 (define note-head-interface
   (lily-interface
    'note-head-interface
@@ -193,7 +242,7 @@ more than this (in staffspace)")
 (define note-name-interface
   (lily-interface
    'note-name-interface
-   "Note naem"
+   "Note name"
    (list
     (property-description 'style symbol? "symbol that sets note name style")
     )
@@ -220,13 +269,13 @@ more than this (in staffspace)")
 (define tuplet-bracket-interface
   (lily-interface
    'tuplet-bracket-interface
-   "A bracket with a number in the middle" 
+   "A bracket with a number in the middle, used for tuplets." 
    (list
     (property-description 'beams list? "list of beam ptrs.")
     (property-description 'columns list? " list of note-columns.")
     (property-description 'number-gap number? "")
-    (property-description 'delta-y number? "")
-    (property-description 'thick number? "")
+    (property-description 'delta-y number? "amount of ascension")
+    (property-description 'thick number? "thickness, in stafflinethickness")
     )
 ))
 
@@ -238,7 +287,7 @@ more than this (in staffspace)")
    (list
     (property-description 'stacking-dir  dir? "stack contents of elements in which direction ?")
     (property-description 'align-dir  dir? "Which side to align? -1: left side, 0: centered around center-element if not nil, or around center of width), 1: right side")
-    (property-description 'threshold  pair? "(cons MIN MAX), where MIN and MAX are dimensions in staffspace")
+    (property-description 'threshold  number-pair? "(cons MIN MAX), where MIN and MAX are dimensions in staffspace")
     (property-description 'alignment-done  boolean? "boolean to administrate whether we've done the alignment already (to ensure that the process is done only once)")
     (property-description 'center-element ly-element? "element which will be at the
 center of the group after aligning (when using
@@ -253,8 +302,8 @@ this object as a reference point.")
    'aligned-interface
    "read by align-interface"
    (list
-    (property-description 'minimum-space pair? "(cons LEFT RIGHT)")
-    (property-description 'extra-space pair? "(cons LEFT RIGHT)")
+    (property-description 'minimum-space number-pair? "(cons LEFT RIGHT)")
+    (property-description 'extra-space number-pair? "(cons LEFT RIGHT)")
     )))
 
 (define break-aligned-interface
@@ -263,22 +312,26 @@ this object as a reference point.")
    "Items that are aligned in prefatory matter"
    (list
     (property-description 'break-align-symbol symbol? "the index in the spacing table (symbol) of the to be aligned item.")
-    (property-description 'visibility-lambda procedure? "")
-    (property-description 'breakable boolean? "")
+    (property-description 'visibility-lambda procedure? "a function that takes the break direction and returns a  cons of booleans containing (TRANSPARENT . EMPTY)")
+    (property-description 'breakable boolean? "boolean indicating if this is a breakable item (clef, barline, key sig, etc.)")
     )))
 
 (define chord-name-interface
   (lily-interface
    'chord-name-interface
-   ""
+   "generate a chord name"
    (list
-    )))
+    (property-description 'pitches list? "list of musical-pitch")
+    (property-description 'inversion list? " musical-pitch, optional")
+    (property-description 'bass list? " musical-pitch, optional")
+   )))
+
 (define time-signature-interface
   (lily-interface
    'time-signature-interface
    "A time signature, in different styles"
    (list
-    (property-description 'fraction pair? "")
+    (property-description 'fraction number-pair? "")
     (property-description 'style string? "")
     )))
 
@@ -287,51 +340,35 @@ this object as a reference point.")
    'bar-line-interface
    "Bar line"
    (list
-    (property-description 'barsize-procedure procedure? "")
-    (property-description 'kern number? "")
-    (property-description 'thin-kern number? "")
-    (property-description 'hair-thickness number? "")
-    (property-description 'thick-thickness number? "")
-    (property-description 'glyph string? "")
+    (property-description 'barsize-procedure procedure? "how to compute the size of a bar line")
+    (property-description 'kern number? "space after a thick line")
+    (property-description 'thin-kern number? "space after a hair-line")
+    (property-description 'hair-thickness number? "thickness, measured in stafflinethickness")
+    (property-description 'thick-thickness number? "thickness, measured in stafflinethickness")
+    (property-description 'glyph string? "what kind barline? A concatenation of |, : and .")
     (property-description 'bar-size number? "")
-    (property-description 'break-glyph-function procedure? "")
+    (property-description 'break-glyph-function procedure? "function taking glyph and break-direction, returning the glyph at a line break")
    )))
 
 
 
 
-(define text-spanner-interface
-  (lily-interface
-   'text-spanner-interface
-   "generic text spanner"
-   (list
-    (property-description 'dash-period  number? "")
-    (property-description 'dash-length number? "")
-    (property-description 'line-thickness number? "")
-    (property-description 'edge-height pair? "(leftheight . rightheight)")
-    (property-description 'edge-text pair? "(lefttext . righttext)")
-    (property-description 'text-style string? "") ; SYMBOL!!?
-    (property-description 'type string? "line, dashed-line or dotted-line") ; SYMBOL!!?    
-    )
-))
-
 (define hairpin-interface
   (lily-interface
    'hairpin-interface
    "hairpin crescendo"
    (list
-    (property-description 'grow-direction dir? "")
-    (property-description 'thickness number? "")
-    (property-description 'height number? "")
+    (property-description 'grow-direction dir? "crescendo or decrescendo?")
+    (property-description 'thickness number? "thickness, measured in stafflinethickness")
+    (property-description 'height number? "height, measured in staffspace in ")
     )))
 
-
 (define arpeggio-interface
   (lily-interface
    'arpeggio-interface
-   "arpeggio "
+   "arpeggio"
    (list
-    (property-description 'stems list? "list of stem objects, corresponding to the notes that the  arp has to be before.")
+    (property-description 'stems list? "list of stem objects, corresponding to the notes that the arpeggio has to be before.")
     )
    )
   )
@@ -355,17 +392,28 @@ this object as a reference point.")
 (define text-interface
   (lily-interface
    'text-interface
-   "A text"
-   (list
-    (property-description 'text string? "")
-    (property-description 'style string? "")
+   "A scheme markup text"
+   (list
+    (property-description 'text (lambda (x) (or (string? x) (list? x))) "the scheme markup text.  Either a string, or a list of which the CAR is a markup '(MARKUP text text ...).  MARKUP is either a CONS: an element property '(key . value) or a symbol: an abbreviation for a list of element properties.  These abbreviations are currently defined: rows lines roman music bold italic named super sub text, as well as all font-style's.")
+    (property-description 'font-style string? "font definition for a special purpose, one of: finger volta timesig mark script large Large dynamic")
+    (property-description 'font-series string? "partial font definition: medium, bold")
+    (property-description 'font-shape string?  "partial font definition: upright or italic")
+    (property-description 'font-family string? "partial font definition: music roman braces dynamic math ...")
+    (property-description 'font-name string? "partial font definition: base name of font file FIXME: should override other partials")
+    (property-description 'font-point string? "partial font definition: exact font size in points FIXME: should override font-size")
+    (property-description 'font-size string? "partial font definition: the relative size, 0 is style-sheet's normal size, -1 is smaller, +1 is bigger")
+    (property-description 'align number? "the alignment of the text, 0 is horizontal, 1 is vertical")
+    (property-description 'lookup symbol? "lookup method: 'value for plain text, 'name for character-name")
+    (property-description 'raise number? "height for text to be raised (a negative value lowers the text")
+    (property-description 'kern number? "amount of extra white space to add before text.  This is `relative'(?) to the current alignment.")
+    (property-description 'magnify number? "the magnification factor.  FIXME: doesn't work for feta fonts")
     )))
 
 
 (define dot-column-interface
   (lily-interface
    'dot-column-interface
-   ""
+   "Interface that groups dots so they form a column"
    (list
     )))
 
@@ -380,14 +428,14 @@ this object as a reference point.")
 (define finger-interface
   (lily-interface
    'finger-interface
-   "Any kind of loudness sign"
+   "A fingering instruction"
    '()
     ))
 
 (define separation-spanner-interface
   (lily-interface
    'separation-spanner-interface
-   ""
+   "Spanner that containing <code>separation-item-interface</code> elements to calculate rods"
    '()
   ))
 (define text-script-interface
@@ -409,8 +457,15 @@ this object as a reference point.")
 (define hara-kiri-group-interface
   (lily-interface
    'hara-kiri-group-interface
-   "seppuku"
-   '()))
+   "  As Vertical_group_spanner, but keep track of interesting items.  If
+  we don't contain any interesting items after linebreaking, then
+  gracefully commit suicide.  Objective: don't disgrace Lily by
+  typesetting empty lines in orchestral scores."
+   (list
+    (property-description 'items-worth-living list? "list of interesting items. If empty in a particular system, clear that system.")
+
+
+    )))
 
 (define lyric-hyphen-interface
   (lily-interface
@@ -432,7 +487,7 @@ syllables.   The length of the hyphen line should stretch based on the
    'key-signature-interface
    "A group of  accidentals."
    (list
-    (property-description 'c0-position  integer? "integer indicating the position of central C?")
+    (property-description 'c0-position  integer? "integer indicating the position of central C")
     (property-description 'old-accidentals  list? "list of (pitch, accidental) pairs")
     (property-description 'new-accidentals  list? "list of (pitch, accidental) pairs")
     )))
@@ -452,7 +507,7 @@ syllables.   The length of the hyphen line should stretch based on the
 (define lyric-syllable-interface
   (lily-interface
    'lyric-syllable-interface
-   ""
+   "a single piece of lyrics"
    (list
     (property-description 'word-space  number? "")
     )))
@@ -461,20 +516,20 @@ syllables.   The length of the hyphen line should stretch based on the
 (define mark-interface
   (lily-interface
    'mark-interface
-   ""
+   "a rehearsal mark"
    (list
     )))
 
 (define multi-measure-rest-interface
   (lily-interface
    'multi-measure-rest-interface
-   ""
+   "A rest that spans a whole number of measures."
    (list
     
     (property-description 'columns  list? "list of paper-columns")
-    (property-description 'expand-limit  integer? "int : max number of measures expanded in church rests")
-    (property-description 'minimum-width number? "Real in staffspace")
-    (property-description 'padding  number? "staffspace")
+    (property-description 'expand-limit  integer? "maximum number of measures expanded in church rests")
+    (property-description 'minimum-width number? "minimum-width of rest symbol, in staffspace")
+    (property-description 'padding  number? "padding between number and rest. Measured in staffspace.")
     )))
 
 (define paper-column-interface
@@ -482,31 +537,40 @@ syllables.   The length of the hyphen line should stretch based on the
    'paper-column-interface
    ""
    (list
+    (property-description 'when moment? "when does this column happen?")
+    (property-description 'bounded-by-me list? "list of spanners that have this
+column as start/begin point. Only columns that have elements or act as bounds are spaced.")
     (property-description 'dir-list  list? "list of stem directions")
     (property-description 'shortest-playing-duration  moment? "duration of the shortest playing in that column.")
     (property-description 'shortest-starter-duration  moment? "duration of the shortest notes that starts exactly in this column.")
     (property-description 'contains-grace  boolean? "Used to widen entries for grace notes.")
-    (property-description 'extra-space  pair? "pair of distances")
-    (property-description 'stretch-distance pair? "pair of distances")
+    (property-description 'extra-space  number-pair? "pair of distances")
+    (property-description 'stretch-distance number-pair? "pair of distances")
     )))
 
 (define spaceable-element-interface
   (lily-interface
    'spaceable-element-interface
-   ""
+   "An element (generally a Paper_column) that takes part in the
+spacing problem. "
    (list
      (property-description 'minimum-distances list? "list of rods (ie. (OBJ . DIST) pairs)")
      (property-description 'ideal-distances  list? "(OBJ . (DIST . STRENGTH)) pairs")
-     (property-description 'dir-list list? "list of stem directions.")
+     (property-description 'dir-list list? "list of stem directions, needed for optical spacing correction.")
      )))
 
 (define rest-collision-interface
   (lily-interface
    'rest-collision-interface
-   ""
-   (list
-    (property-description 'maximum-rest-count integer? "")
-    (property-description 'minimum-distance number? "")    
+   "Move around ordinary rests (not multi-measure-rests) to avoid
+conflicts."
+   (list
+    (property-description 'maximum-rest-count integer? "kill off rests so we don't more than this number left.")
+    (property-description 'minimum-distance number? "minimum distance between notes and rests.")
+    (property-description 'elements list? "list of elements (NoteColumn,
+generally) participating in the collision. The
+<code>rest-collision</code> property in <code>elements</code> is set
+to a pointer to the collision")
     )))
 
 (define script-interface
@@ -514,13 +578,13 @@ syllables.   The length of the hyphen line should stretch based on the
    'script-interface
    ""
    (list
-    (property-description 'script-priority number? "")
+    (property-description 'script-priority number? "A sorting key that determines in what order a script is within a stack of scripts")
     )))
 
 (define script-column-interface
   (lily-interface
    'script-column-interface
-   ""
+   "An interface that sorts scripts according to their <code>script-priority</code>"
    (list )))
 
 
@@ -538,8 +602,8 @@ syllables.   The length of the hyphen line should stretch based on the
    "This spanner draws the lines of a staff.  The middle line is
 position 0."
    (list
-    (property-description 'staff-space number? "")
-    (property-description 'line-count integer? "")
+    (property-description 'staff-space number? "Amount of line leading relative to global staffspace")
+    (property-description 'line-count integer? "Number of staff lines")
     )))
 
 (define stem-tremolo-interface
@@ -548,17 +612,23 @@ position 0."
    ""
    (list
     (property-description 'stem ly-element? "pointer to the stem object.")
-    (property-description 'beam-width number? "")
-    (property-description 'beam-thickness number? "")
-    (property-description 'beam-space-function procedure? "")
+    (property-description 'beam-width number? "width of the tremolo sign")
+    (property-description 'beam-thickness number? "thickness, measured in staffspace")
+    (property-description 'beam-space-function procedure? "function returning space given multiplicity")
     )))
 
 (define separation-item-interface
   (lily-interface
    'separation-item-interface
-   ""
-   (list
-    )))
+   "Item that computes widths to generate spacing rods.
+<p>
+Calc dimensions for the Separating_group_spanner; this has to be
+   an item to get dependencies correct.  It can't be an element_group
+   since these usually are in a different X_group
+"
+   (list
+    (property-description 'elements list? " -- list of items.")
+     )))
 
 (define sustain-pedal-interface
   (lily-interface
@@ -572,15 +642,33 @@ position 0."
    ""
    (list
     (property-description 'collapse-height number? "")
-    (property-description 'thickness number? "")
+    (property-description 'thickness number? "thickness, measured in stafflinethickness")
+
+    ; Should collapse into (bracket . ((height . ) ... ))
+    ;
     (property-description 'arch-height number? "")
     (property-description 'arch-angle number? "")
     (property-description 'arch-thick number? "")
     (property-description 'arch-width number? "")
     (property-description 'bracket-thick number? "")
     (property-description 'bracket-width number? "")
+    (property-description 'glyph symbol? "bar-line, bracket or brace")
     )))
 
+(define text-spanner-interface
+  (lily-interface
+   'text-spanner-interface
+   "generic text spanner"
+   (list
+    (property-description 'dash-period  number? "the length of one dash + white space")
+    (property-description 'dash-length number? "the length of a dash")
+    (property-description 'line-thickness number? "the thickness[stafflinethickness] of the line")
+    (property-description 'edge-height pair? "a cons that specifies the heights of the vertical egdes '(LEFT-height . RIGHT-height)")
+    (property-description 'edge-text pair? "a cons that specifies the texts to be set at the edges '(LEFT-text . RIGHT-text)")
+    (property-description 'type string? "one of: line, dashed-line or dotted-line") ; SYMBOL!!?    
+    )
+))
+
 (define text-script-interface
   (lily-interface
    'text-script-interface
@@ -589,17 +677,20 @@ position 0."
     
     )))
 
+
 (define tie-interface
   (lily-interface
    'tie-interface
-   ""
+   "A tie connecting two noteheads."
    (list
-    (property-description 'staffline-clearance number? "")
+    (property-description 'staffline-clearance number? "don't get closer than this to stafflines.")
+    (property-description 'control-points list? "List of 4 offsets (number-pairs) controlling the tie shape")
     (property-description 'heads pair? "pair of element pointers, pointing to the two heads of the  tie. ")
-    (property-description 'details list? "")
-    (property-description 'thickness number? "")
-    (property-description 'x-gap number? "")
-    (property-description 'minimum-length number? "")
+    (property-description 'details list? "alist of parameters for the curve shape")
+    (property-description 'thickness number? "thickness, measured in stafflinethickness")
+    (property-description 'x-gap number? "horizontal gap between notehead and tie")
+    (property-description 'direction dir? "up or down?")    
+    (property-description 'minimum-length number? "minimum length in staffspace")
     )))
 
 
@@ -607,7 +698,7 @@ position 0."
 (define tie-column-interface
   (lily-interface
    'tie-column-interface
-   ""
+   "that sets tie directions in a tied chord"
    (list
     )))
 
@@ -617,7 +708,7 @@ position 0."
    "Volta bracket with number"
    (list
     (property-description 'bars  list? "list of barline ptrs.")
-    (property-description 'thickness  number? "in stafflinethickness")
+    (property-description 'thickness  number? "thickness, measured in stafflinethickness")
     (property-description 'height  number? "in staffspace ")
     )))
 
diff --git a/scm/slur.scm b/scm/slur.scm
index 2c10991f07..a17cf91fd0 100644
--- a/scm/slur.scm
+++ b/scm/slur.scm
@@ -77,7 +77,7 @@
 
 ;; This list defines the offsets for each type of attachment.
 ;; The format of each element is
-;; (stem-dir * dir . slur-dir * dir)
+;; (attachment stem-dir*dir slur-dir*dir)
 ;; Different attachments have different default points:
 ;;
 ;; head: Default position is centered in X, on outer side of head Y
@@ -115,6 +115,6 @@
    (y-free . 0.75)
    (attachment-offset . ((0 . 0) . (0 . 0)))
    (slope-limit . 0.8)
-   (meta . ,(element-description "Slur" general-element-interface slur-interface))
+   (meta . ,(element-description "Slur" slur-interface))
    )
   )
-- 
2.39.5