release commit

[lilypond.git] / lily / item.cc

diff --git a/lily/item.cc b/lily/item.cc
index c3e8c38569187870043919a3aa1242eed2de241f..64d6c39637e2cf279a40f1825e2f96655c2b81a6 100644 (file)
--- a/lily/item.cc
+++ b/lily/item.cc
@@ -6,7 +6,6 @@
   (c)  1997--2003 Han-Wen Nienhuys <hanwen@cs.uu.nl>
 */
 
-
 #include "paper-score.hh"
 #include "warn.hh"
 #include "item.hh"
@@ -193,12 +192,38 @@ unsmob_item (SCM s )
 
 ADD_INTERFACE(Item,
              "item-interface",
-             "
-
-Grobs can be distinguished in their role in the horizontal spacing.
-Many grobs define constraints on the spacing by their sizes. For
-example, note heads, clefs, stems, and all other symbols with a fixed
-shape.  These grobs form a subtype called @code{Item}.
-
-",
+             "\n"
+             "\n"
+             "Grobs can be distinguished in their role in the horizontal spacing.\n"
+             "Many grobs define constraints on the spacing by their sizes. For\n"
+             "example, note heads, clefs, stems, and all other symbols with a fixed\n"
+             "shape.  These grobs form a subtype called @code{Item}.\n"
+             "\n"
+             "\n"
+             "Some items need special treatment for line breaking. For example, a\n"
+             "clef is normally only printed at the start of a line (i.e. after a\n"
+             "line break).  To model this, `breakable' items (clef, key signature,\n"
+             "bar lines, etc.) are copied twice. Then we have three versions of each\n"
+             "breakable item: one version if there is no line break, one version\n"
+             "that is printed before the line break (at the end of a system), one\n"
+             "version that is printed after the line break.\n"
+             "\n"
+             "Whether these versions are visible and take up space, is determined by\n"
+             "the outcome of the @code{break-visibility}. This grob property is a\n"
+             "function taking a direction (-1, 0 or 1) as argument. It returns a\n"
+             "cons of booleans, signifying whether this grob should be transparent\n"
+             "and have no extent.\n"
+             "\n"
+             "The following variables for break-visibility are predefined:\n"
+             "@example\n"
+             "           grob will show:   before  no     after\n"
+             "                             break   break  break\n"
+             "  all-invisible              no      no     no\n"
+             "  begin-of-line-visible      no      no     yes\n"
+             "  end-of-line-visible        yes     no     no\n"
+             "  all-visible                yes     yes    yes\n"
+             "  begin-of-line-invisible    yes     yes    no\n"
+             "  end-of-line-invisible      no      yes    yes\n"
+             "@end example\n"
+             ,
              "no-spacing-rods break-visibility breakable")