Imported Upstream version 2.19.45

[lilypond.git] / scm / define-grob-properties.scm

diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index 6f3a7704efc075714cce5233904b90b550e0e11d..cb9103a6fcda899fe88d459af846f724e5e01e92 100644 (file)
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -1,6 +1,6 @@
 ;;;; This file is part of LilyPond, the GNU music typesetter.
 ;;;;
 ;;;; This file is part of LilyPond, the GNU music typesetter.
 ;;;;

-;;;; Copyright (C) 1998--2012  Han-Wen Nienhuys <hanwen@xs4all.nl>
+;;;; Copyright (C) 1998--2015  Han-Wen Nienhuys <hanwen@xs4all.nl>

 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 ;;;;
 ;;;; LilyPond is free software: you can redistribute it and/or modify
 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 ;;;;
 ;;;; LilyPond is free software: you can redistribute it and/or modify


@@ -125,43 +125,47 @@ visibility of the tuplet bracket.  Setting it to false prevents
 printing of the bracket.  Setting the property to @code{if-no-beam}
 makes it print only if there is no beam associated with this tuplet
 bracket.")
 printing of the bracket.  Setting the property to @code{if-no-beam}
 makes it print only if there is no beam associated with this tuplet
 bracket.")

-     (break-align-anchor ,number? "Grobs aligned to this break-align
-grob will have their X-offsets shifted by this number.  In bar lines,
+     (break-align-anchor ,number? "Grobs aligned to this breakable
+item will have their X-offsets shifted by this number.  In bar lines,

 for example, this is used to position grobs relative to the (visual)
 center of the bar line.")
      (break-align-anchor-alignment ,number? "Read by
 @code{ly:break-aligned-interface::calc-extent-aligned-anchor} for
 aligning an anchor to a grob's extent.")
 for example, this is used to position grobs relative to the (visual)
 center of the bar line.")
      (break-align-anchor-alignment ,number? "Read by
 @code{ly:break-aligned-interface::calc-extent-aligned-anchor} for
 aligning an anchor to a grob's extent.")

-     (break-align-orders ,vector? "Defines the order in which
-prefatory matter (clefs, key signatures) appears.  The format is a
-vector of length@tie{}3, where each element is one order for
-end-of-line, middle of line, and start-of-line, respectively.  An
-order is a list of symbols.
+     (break-align-orders ,vector? "This is a vector of 3@tie{}lists:
+@w{@code{#(@var{end-of-line} @var{unbroken} @var{start-of-line}}}).
+Each list contains @w{@emph{break-align symbols}} that specify an
+order of breakable items (see @rinternals{break-alignment-interface}).

 
 

-For example, clefs are put after key signatures by setting
+For example, this places time signatures before clefs:

 
 @example
 
 @example

-\\override Score.BreakAlignment #'break-align-orders =
-  #(make-vector 3 '(span-bar
+\\override Score.BreakAlignment.break-align-orders =
+  #(make-vector 3 '(left-edge
+                    cue-end-clef
+                    ambitus

                     breathing-sign
                     breathing-sign

-                    staff-bar
-                    key
+                    time-signature

                     clef
                     clef

-                    time-signature))
+                    cue-clef
+                    staff-bar
+                    key-cancellation
+                    key-signature
+                    custos))

 @end example")
 @end example")

-     (break-align-symbol ,symbol? "This key is used for aligning and
-spacing breakable items.")
-     (break-align-symbols ,list? "A list of symbols that determine
-which break-aligned grobs to align this to.  If the grob selected by
-the first symbol in the list is invisible due to break-visibility, we
-will align to the next grob (and so on).  Choices are @code{left-edge},
-@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{staff-bar},
-@code{key-cancellation}, @code{key-signature}, @code{time-signature},
-and @code{custos}.")
+     (break-align-symbol ,symbol? "This key is used for aligning,
+ordering, and spacing breakable items.  See
+@rinternals{break-alignment-interface}.")
+     (break-align-symbols ,list? "A list of
+@w{@emph{break-align symbols}} that determines which breakable
+items to align this to.  If the grob selected by the first symbol
+in the list is invisible due to @w{@code{break-visibility}}, we
+will align to the next grob (and so on).  Choices are listed in
+@rinternals{break-alignment-interface}.")

      (break-overshoot ,number-pair? "How much does a broken spanner
 stick out of its bounds?")
      (break-visibility ,vector? "A vector of 3@tie{}booleans,
      (break-overshoot ,number-pair? "How much does a broken spanner
 stick out of its bounds?")
      (break-visibility ,vector? "A vector of 3@tie{}booleans,

-@code{#(@var{end-of-line} @var{unbroken} @var{begin-of-line})}.
+@w{@code{#(@var{end-of-line} @var{unbroken} @var{begin-of-line})}}.

 @code{#t} means visible, @code{#f} means killed.")
      (breakable ,boolean? "Allow breaks here.")
      (broken-bound-padding ,number? "The amount of padding to insert
 @code{#t} means visible, @code{#f} means killed.")
      (breakable ,boolean? "Allow breaks here.")
      (broken-bound-padding ,number? "The amount of padding to insert


@@ -170,19 +174,19 @@ when a spanner is broken at a line break.")
 ;;;
 ;;; c
 ;;;
 ;;;
 ;;; c
 ;;;

+     (chord-dots-limit ,integer? "Limits the column of dots
+on each chord to the height of the chord plus
+@code{chord-dots-limit} staff-positions.")

      (circled-tip ,boolean? "Put a circle at start/@/end of
 hairpins (al/@/del niente).")
      (circled-tip ,boolean? "Put a circle at start/@/end of
 hairpins (al/@/del niente).")

+     (clef-alignments ,list? "An alist of parent-alignments
+that should be used for clef modifiers with various clefs")

      (clip-edges ,boolean? "Allow outward pointing beamlets at the
 edges of beams?")
      (collapse-height ,ly:dimension? "Minimum height of system start
 delimiter.  If equal or smaller, the bracket/@/brace/@/line is removed.")
      (clip-edges ,boolean? "Allow outward pointing beamlets at the
 edges of beams?")
      (collapse-height ,ly:dimension? "Minimum height of system start
 delimiter.  If equal or smaller, the bracket/@/brace/@/line is removed.")

-     (collision-bias ,number? "Number determining how much to favor the
-left (negative) or right (positive).  Larger absolute values in either
-direction will push a collision in this direction.")

      (collision-interfaces ,list? "A list of interfaces for which
 automatic beam-collision resolution is run.")
      (collision-interfaces ,list? "A list of interfaces for which
 automatic beam-collision resolution is run.")

-     (collision-padding ,number? "Amount of padding to apply after
-a collision is detected via the self-alignment-interface.")

      (collision-voice-only ,boolean? "Does automatic beam collsion apply
 only to the voice in which the beam was created?")
      (color ,color? "The color of this grob.")
      (collision-voice-only ,boolean? "Does automatic beam collsion apply
 only to the voice in which the beam was created?")
      (color ,color? "The color of this grob.")


@@ -195,7 +199,7 @@ measure of the closeness of the inner stems.  It is used for damping
 the slope of the beam.")
      (connect-to-neighbor ,pair? "Pair of booleans, indicating whether
 this grob looks as a continued break.")
 the slope of the beam.")
      (connect-to-neighbor ,pair? "Pair of booleans, indicating whether
 this grob looks as a continued break.")

-     (control-points ,list? "List of offsets (number pairs) that form
+     (control-points ,number-pair-list? "List of offsets (number pairs) that form

 control points for the tie, slur, or bracket shape.  For B@'eziers,
 this should list the control points of a third-order B@'ezier curve.")
      (count-from ,integer? "The first measure in a measure count
 control points for the tie, slur, or bracket shape.  For B@'eziers,
 this should list the control points of a third-order B@'ezier curve.")
      (count-from ,integer? "The first measure in a measure count


@@ -210,8 +214,9 @@ increments from this initial value.")
 dash structure.  Each @code{dash-element} has a starting t value,
 an ending t-value, a @code{dash-fraction}, and a @code{dash-period}.")
      (dash-fraction ,number? "Size of the dashes, relative to
 dash structure.  Each @code{dash-element} has a starting t value,
 an ending t-value, a @code{dash-fraction}, and a @code{dash-period}.")
      (dash-fraction ,number? "Size of the dashes, relative to

-@code{dash-period}.  Should be between @code{0.0} (no line) and
-@code{1.0} (continuous line).")
+@code{dash-period}.  Should be between @code{0.1} and
+@code{1.0} (continuous line).  If set to @code{0.0}, a dotted line is
+produced")

      (dash-period ,number? "The length of one dash together with
 whitespace.  If negative, no line is drawn at all.")
      (default-direction ,ly:dir? "Direction determined by note head
      (dash-period ,number? "The length of one dash together with
 whitespace.  If negative, no line is drawn at all.")
      (default-direction ,ly:dir? "Direction determined by note head


@@ -241,6 +246,11 @@ elements closer together.")
      (dot-placement-list ,list? "List consisting of
 @code{(@var{description} @var{string-number} @var{fret-number}
 @var{finger-number})} entries used to define fret diagrams.")
      (dot-placement-list ,list? "List consisting of
 @code{(@var{description} @var{string-number} @var{fret-number}
 @var{finger-number})} entries used to define fret diagrams.")

+     (double-stem-separation ,number? "The distance between the two
+stems of a half note in tablature when using @code{\\tabFullNotation},
+not counting the width of the stems themselves, expressed as a multiple
+of the default height of a staff-space in the traditional five-line
+staff.")

      (duration-log ,integer? "The 2-log of the note head duration,
 i.e., @code{0} = whole note, @code{1} = half note, etc.")
 
      (duration-log ,integer? "The 2-log of the note head duration,
 i.e., @code{0} = whole note, @code{1} = half note, etc.")
 


@@ -283,6 +293,10 @@ set this to @code{(+inf.0 . -inf.0)}.")
 ;;; f
 ;;;
      (flag-count ,number? "The number of tremolo beams.")
 ;;; f
 ;;;
      (flag-count ,number? "The number of tremolo beams.")

+     (flag-style ,symbol? "The style of the flag to be used with
+@code{MetronomeMark}. Available are @code{'modern-straight-flag},
+@code{'old-straight-flag}, @code{flat-flag}, @code{mensural} and
+@code{'default}")

      (flat-positions ,list? "Flats in key signatures are placed
 within the specified ranges of staff-positions.  The general form
 is a list of pairs, with one pair for each type of clef, in order
      (flat-positions ,list? "Flats in key signatures are placed
 within the specified ranges of staff-positions.  The general form
 is a list of pairs, with one pair for each type of clef, in order


@@ -310,7 +324,9 @@ include @code{upright}, @code{italic}, @code{caps}.")
 @q{normal}@tie{}size.  @code{0}@tie{}is style-sheet's normal size,
 @w{@code{-1}} is smaller, @code{+1} is bigger.  Each step of@tie{}1 is
 approximately 12% larger; 6@tie{}steps are exactly a factor@tie{}2
 @q{normal}@tie{}size.  @code{0}@tie{}is style-sheet's normal size,
 @w{@code{-1}} is smaller, @code{+1} is bigger.  Each step of@tie{}1 is
 approximately 12% larger; 6@tie{}steps are exactly a factor@tie{}2

-larger.  Fractional values are allowed.")
+larger.  If the context property @code{fontSize} is set, its value is
+added to this before the glyph is printed.  Fractional values are
+allowed.")

      (footnote ,boolean? "Should this be a footnote or in-note?")
      (footnote-music ,ly:music? "Music creating a footnote.")
      (footnote-text ,markup? "A footnote for the grob.")
      (footnote ,boolean? "Should this be a footnote or in-note?")
      (footnote-music ,ly:music? "Music creating a footnote.")
      (footnote-text ,markup? "A footnote for the grob.")


@@ -367,6 +383,13 @@ label the lowest fret number.  Default@tie{}0.5.
 the center of the fret in direction parallel to strings.
 Default@tie{}0.
 @item
 the center of the fret in direction parallel to strings.
 Default@tie{}0.
 @item

+@code{fret-label-horizontal-offset} -- The offset of the fret label from
+the center of the fret in direction orthogonal to strings.
+Default@tie{}0.
+@item
+@code{paren-padding} -- The padding for the parenthesis.
+Default@tie{}0.05.
+@item

 @code{label-dir} -- Side to which the fret label is attached.
 @w{@code{-1}}, @code{LEFT}, or @code{DOWN} for left or down; @code{1},
 @code{RIGHT}, or @code{UP} for right or up.  Default @code{RIGHT}.
 @code{label-dir} -- Side to which the fret label is attached.
 @w{@code{-1}}, @code{LEFT}, or @code{DOWN} for left or down; @code{1},
 @code{RIGHT}, or @code{UP} for right or up.  Default @code{RIGHT}.


@@ -447,7 +470,9 @@ etc. are already taken.")
 ;;; h
 ;;;
      (hair-thickness ,number? "Thickness of the thin line in a bar
 ;;; 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
      (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


@@ -506,6 +531,8 @@ the string will be assigned to the @code{id} attribute of a group (<g>)
 that encloses the stencils that comprise the grob.  In the Postscript
 backend, as there is no way to group items, the setting of the id property
 will have no effect.")
 that encloses the stencils that comprise the grob.  In the Postscript
 backend, as there is no way to group items, the setting of the id property
 will have no effect.")

+     (ignore-ambitus ,boolean? "If set, don't consider this notehead
+for ambitus calculation.")

      (ignore-collision ,boolean? "If set, don't do note collision
 resolution on this @code{NoteColumn}.")
      (implicit ,boolean? "Is this an implicit bass figure?")
      (ignore-collision ,boolean? "If set, don't do note collision
 resolution on this @code{NoteColumn}.")
      (implicit ,boolean? "Is this an implicit bass figure?")


@@ -520,12 +547,17 @@ 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.")
 ;;;
      (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 individual elements
+in any compound 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}).")

      (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
 correction and @code{1} for full correction.")
      (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
 correction and @code{1} for full correction.")

+     (knee-to-beam ,boolean? "Determines whether a tuplet number
+will be positioned next to a kneed beam.")

 
 
 ;;;
 
 
 ;;;


@@ -543,8 +575,13 @@ lines for.")
 lines.  It is the sum of 2@tie{}numbers: The first is the factor for
 line thickness, and the second for staff space.  Both contributions
 are added.")
 lines.  It is the sum of 2@tie{}numbers: The first is the factor for
 line thickness, and the second for staff space.  Both contributions
 are added.")

-     (ledger-positions ,list? "Repeating pattern for the vertical positions
-of ledger lines.  Bracketed groups are always shown together.")
+     (ledger-positions ,list? "Vertical positions of ledger lines.
+When set on a @code{StaffSymbol} grob it defines a repeating
+pattern of ledger lines and any parenthesized groups will always be
+shown together.")
+     (ledger-positions-function ,scheme? "A quoted Scheme procedure that
+takes a @code{StaffSymbol} grob and the vertical position of a note head
+as arguments and returns a list of ledger line positions.")

      (left-bound-info ,list? "An alist of properties for determining
 attachments of spanners to edges.")
      (left-padding ,ly:dimension? "The amount of space that is put
      (left-bound-info ,list? "An alist of properties for determining
 attachments of spanners to edges.")
      (left-padding ,ly:dimension? "The amount of space that is put


@@ -564,8 +601,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.")
 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}.")
 
 
      (long-text ,markup? "Text markup.  See @ruser{Formatting text}.")
 
 


@@ -574,9 +615,6 @@ contour.")
 ;;;
      (max-beam-connect ,integer? "Maximum number of beams to connect
 to beams from this stem.  Further beams are typeset as beamlets.")
 ;;;
      (max-beam-connect ,integer? "Maximum number of beams to connect
 to beams from this stem.  Further beams are typeset as beamlets.")

-     (max-stretch ,number? "The maximum amount that this
-@code{VerticalAxisGroup} can be vertically stretched (for example, in
-order to better fill a page).")

      (maximum-gap ,number? "Maximum value allowed for @code{gap}
 property.")
      (measure-count ,integer? "The number of measures for a
      (maximum-gap ,number? "Maximum value allowed for @code{gap}
 property.")
      (measure-count ,integer? "The number of measures for a


@@ -604,6 +642,11 @@ this long, normally in the horizontal direction.  This requires an
 appropriate callback for the @code{springs-and-rods} property.  If
 added to a @code{Tie}, this sets the minimum distance between
 noteheads.")
 appropriate callback for the @code{springs-and-rods} property.  If
 added to a @code{Tie}, this sets the minimum distance between
 noteheads.")

+     (minimum-length-after-break ,ly:dimension? "If set, try to make
+a broken spanner starting a line this long.  This requires an
+appropriate callback for the @code{springs-and-rods} property.  If
+added to a @code{Tie}, this sets the minimum distance to the
+notehead.")

      (minimum-length-fraction ,number? "Minimum length of ledger line
 as fraction of note head size.")
      (minimum-space ,ly:dimension? "Minimum distance that the victim
      (minimum-length-fraction ,number? "Minimum length of ledger line
 as fraction of note head size.")
      (minimum-space ,ly:dimension? "Minimum distance that the victim


@@ -632,7 +675,7 @@ object.")
 get stems extending to the middle staff line.")
      (non-break-align-symbols ,list? "A list of symbols that determine
 which NON-break-aligned interfaces to align this to.")
 get stems extending to the middle staff line.")
      (non-break-align-symbols ,list? "A list of symbols that determine
 which NON-break-aligned interfaces to align this to.")

-     (non-default ,boolean? "Set for manually specified clefs.")
+     (non-default ,boolean? "Set for manually specified clefs and keys.")

      (non-musical ,boolean? "True if the grob belongs to a
 @code{NonMusicalPaperColumn}.")
      (nonstaff-nonstaff-spacing ,list? "The spacing alist
      (non-musical ,boolean? "True if the grob belongs to a
 @code{NonMusicalPaperColumn}.")
      (nonstaff-nonstaff-spacing ,list? "The spacing alist


@@ -665,6 +708,13 @@ over the total spanner, where the width of the spanner is normalized
 between 0 and 1.")
      (note-names ,vector? "Vector of strings containing names for
 easy-notation note heads.")
 between 0 and 1.")
      (note-names ,vector? "Vector of strings containing names for
 easy-notation note heads.")

+     (note-collision-threshold ,ly:dimension? "Simultaneous notes that
+are this close or closer in units of @code{staff-space} will be
+identified as vertically colliding. Used by @code{Stem} grobs for notes
+in the same voice, and @code{NoteCollision} grobs for notes in
+different voices. Default value@tie{}1.")
+     (number-type ,symbol? "Numbering style. Choices include
+@code{roman-lower}, @code{roman-upper} and @code{arabic}.")

 
 
 ;;;
 
 
 ;;;


@@ -725,6 +775,19 @@ at a column with a negative penalty.")
      (page-turn-permission ,symbol? "Instructs the page breaker on
 whether to put a page turn at this column.  Can be @code{force} or
 @code{allow}.")
      (page-turn-permission ,symbol? "Instructs the page breaker on
 whether to put a page turn at this column.  Can be @code{force} or
 @code{allow}.")

+     (parent-alignment-X ,number? "Specify on which point
+of the parent the object is aligned. The value @w{@code{-1}} means
+aligned on parent's left edge, @code{0}@tie{}on@tie{}center, and
+@code{1}@tie{}right edge, in X@tie{}direction.  Other numerical
+values may also be specified - the unit is half the parent's width.
+If unset, the value from @code{self-alignment-X} property will be
+used.")
+     (parent-alignment-Y ,number? "Like @code{parent-alignment-X}
+but for the Y@tie{}axis.")
+     (parenthesis-friends ,list? "A list of Grob types, as symbols.
+When parentheses enclose a Grob that has 'parenthesis-friends, the
+parentheses widen to include any child Grobs with type among
+'parenthesis-friends.")

      (parenthesized ,boolean? "Parenthesize this grob.")
      (positions ,number-pair? "Pair of staff coordinates
 @code{(@var{left} . @var{right})}, where both @var{left} and
      (parenthesized ,boolean? "Parenthesize this grob.")
      (positions ,number-pair? "Pair of staff coordinates
 @code{(@var{left} . @var{right})}, where both @var{left} and


@@ -746,6 +809,12 @@ number, the quicker the slur attains its @code{height-limit}.")
 interesting items.")
      (remove-first ,boolean? "Remove the first staff of an orchestral
 score?")
 interesting items.")
      (remove-first ,boolean? "Remove the first staff of an orchestral
 score?")

+     (remove-layer ,integer? "The @code{Keep_alive_together_engraver}
+removes all @code{VerticalAxisGroup} grobs with a @code{remove-layer}
+larger than the smallest retained @code{remove-layer}.  Set to
+@code{#f} to make a layer invisible to the
+@code{Keep_alive_together_engraver}, set to @code{'()} to have it not
+participate in the layering decisions.")

      (replacement-alist ,list? "Alist of strings.
 The key is a string of the pattern to be replaced.  The value is a
 string of what should be displayed.  Useful for ligatures.")
      (replacement-alist ,list? "Alist of strings.
 The key is a string of the pattern to be replaced.  The value is a
 string of what should be displayed.  Useful for ligatures.")


@@ -778,12 +847,20 @@ stem distance.")
 scripts in a stack, by being added to the position of the script in
 the user input, the sum being the overall priority.  Smaller means
 closer to the head.")
 scripts in a stack, by being added to the position of the script in
 the user input, the sum being the overall priority.  Smaller means
 closer to the head.")

+     (segno-kern ,number? "The space between the two thin lines
+of the segno bar line symbol, 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}).")

      (self-alignment-X ,number? "Specify alignment of an object.  The
 value @w{@code{-1}} means left aligned, @code{0}@tie{}centered, and
 @code{1}@tie{}right-aligned in X@tie{}direction.  Other numerical
      (self-alignment-X ,number? "Specify alignment of an object.  The
 value @w{@code{-1}} means left aligned, @code{0}@tie{}centered, and
 @code{1}@tie{}right-aligned in X@tie{}direction.  Other numerical

-values may also be specified.")
+values may also be specified - the unit is half the object width.")

      (self-alignment-Y ,number? "Like @code{self-alignment-X} but for
 the Y@tie{}axis.")
      (self-alignment-Y ,number? "Like @code{self-alignment-X} but for
 the Y@tie{}axis.")

+     (shape ,symbol? "This setting determines what shape a grob
+has.  Valid choices depend on the @code{stencil} callback reading
+this property.")

      (sharp-positions ,list? "Sharps in key signatures are placed
 within the specified ranges of staff-positions.  The general form
 is a list of pairs, with one pair for each type of clef, in order
      (sharp-positions ,list? "Sharps in key signatures are placed
 within the specified ranges of staff-positions.  The general form
 is a list of pairs, with one pair for each type of clef, in order


@@ -795,9 +872,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.")
      (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.")
 @rinternals{spacing-spanner-interface}.")
      (shortest-playing-duration ,ly:moment? "The duration of the
 shortest note playing here.")


@@ -812,7 +888,8 @@ placed vertically.")
 object.")
      (simple-Y ,boolean? "Should the Y placement of a spanner
 disregard changes in system heights?")
 object.")
      (simple-Y ,boolean? "Should the Y placement of a spanner
 disregard changes in system heights?")

-     (size ,number? "Size of object, relative to standard size.")
+     (size ,number? "The ratio of the size of the object to its default
+size.")

      (skip-quanting ,boolean? "Should beam quanting be skipped?")
      (skyline-horizontal-padding ,number? "For determining the
 vertical distance between two staves, it is possible to have a
      (skip-quanting ,boolean? "Should beam quanting be skipped?")
      (skyline-horizontal-padding ,number? "For determining the
 vertical distance between two staves, it is possible to have a


@@ -831,19 +908,78 @@ elements closer together.")
      (slur-padding ,number? "Extra distance between slur and script.")
      (snap-radius ,number? "The maximum distance between two objects that
 will cause them to snap to alignment along an axis.")
      (slur-padding ,number? "Extra distance between slur and script.")
      (snap-radius ,number? "The maximum distance between two objects that
 will cause them to snap to alignment along an axis.")

-     (space-alist ,list? "A table that specifies distances between
-prefatory items, like clef and time-signature.  The format is an alist
-of spacing tuples: @code{(@var{break-align-symbol} @var{type}
-. @var{distance})}, where @var{type} can be the symbols
-@code{minimum-space} or @code{extra-space}.")
+     (space-alist ,list? "An alist that specifies distances from this
+grob to other breakable items, using the format:
+
+@example
+'((@var{break-align-symbol} . (@var{spacing-style} . @var{space}))
+  (@var{break-align-symbol} . (@var{spacing-style} . @var{space}))
+  ...)
+@end example
+
+Standard choices for @w{@code{@var{break-align-symbol}}} are listed in
+@rinternals{break-alignment-interface}.  Additionally, three special
+@w{break-align} symbols available to @w{@code{space-alist}} are:
+
+@quotation
+@table @code
+@item first-note
+used when the grob is just left of the first note on a line
+
+@item next-note
+used when the grob is just left of any other note;
+if not set, the value of @code{first-note} gets used
+
+@item right-edge
+used when the grob is the last item on the line (only compatible with
+the @w{@code{extra-space}} spacing style)
+@end table
+@end quotation
+
+Choices for @code{@var{spacing-style}} are:
+
+@quotation
+@table @code
+@item extra-space
+Put this much space between the two grobs.  The space is stretchable
+when paired with @w{@code{first-note}} or @w{@code{next-note}};
+otherwise it is fixed.
+
+@item minimum-space
+Put at least this much space between the left sides of both grobs,
+without allowing them to collide.  The space is stretchable when paired
+with @w{@code{first-note}} or @w{@code{next-note}}; otherwise it
+is fixed.  Not compatible with @w{@code{right-edge}}.
+
+@item fixed-space
+Only compatible with @w{@code{first-note}} and
+@w{@code{next-note}}.  Put this much fixed space between the grob
+and the note.
+
+@item minimum-fixed-space
+Only compatible with @w{@code{first-note}} and
+@w{@code{next-note}}.  Put at least this much fixed space between
+the left side of the grob and the left side of the note, without
+allowing them to collide.
+
+@item semi-fixed-space
+Only compatible with @w{@code{first-note}} and
+@w{@code{next-note}}.  Put this much space between the grob and
+the note, such that half of the space is fixed and half is
+stretchable.
+@end table
+@end quotation
+
+Rules for this spacing are much more complicated than this.
+See [Wanske] page 126--134, [Ross] page 143--147.")

      (space-to-barline ,boolean? "If set, the distance between a note
 and the following non-musical column will be measured to the bar line
 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.")
      (space-to-barline ,boolean? "If set, the distance between a note
 and the following non-musical column will be measured to the bar line
 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.
 @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.


@@ -953,11 +1089,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}.")
      (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}.")
-     (thin-kern ,number? "The space after a hair-line in a bar line.")
+     (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}).")

      (tie-configuration ,list? "List of @code{(@var{position} .
 @var{dir})} pairs, indicating the desired tie configuration, where
 @var{position} is the offset from the center of the staff in staff
      (tie-configuration ,list? "List of @code{(@var{position} .
 @var{dir})} pairs, indicating the desired tie configuration, where
 @var{position} is the offset from the center of the staff in staff


@@ -969,9 +1111,15 @@ automatically.")
 line just before it would otherwise stop.")
      (toward-stem-shift ,number? "Amount by which scripts are shifted
 toward the stem if their direction coincides with the stem direction.
 line just before it would otherwise stop.")
      (toward-stem-shift ,number? "Amount by which scripts are shifted
 toward the stem if their direction coincides with the stem direction.

-@code{0.0} means keep the default position (centered on the note
-head), @code{1.0} means centered on the stem.  Interpolated values are
-possible.")
+@code{0.0} means centered on the note head (the default position of
+most scripts); @code{1.0} means centered on the stem.  Interpolated
+values are possible.")
+     (toward-stem-shift-in-column ,number? "Amount by which a script
+is shifted toward the stem if its direction coincides with the stem
+direction and it is associated with a @code{ScriptColumn} object.
+@code{0.0} means centered on the note head (the default position of
+most scripts); @code{1.0} means centered on the stem.  Interpolated
+values are possible.")

      (transparent ,boolean? "This makes the grob invisible.")
 
 
      (transparent ,boolean? "This makes the grob invisible.")
 
 


@@ -979,8 +1127,8 @@ possible.")
 ;;; u
 ;;;
      (uniform-stretching ,boolean? "If set, items stretch
 ;;; 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
      (used ,boolean? "If set, this spacing column is kept in the
 spacing problem.")
      (usable-duration-logs ,list? "List of @code{duration-log}s that


@@ -993,15 +1141,22 @@ positioning?")
 ;;;
      (vertical-skylines ,ly:skyline-pair? "Two skylines, one above and
 one below this grob.")
 ;;;
      (vertical-skylines ,ly:skyline-pair? "Two skylines, one above and
 one below this grob.")

+     (voiced-position ,number? "The staff-position of a voiced
+@code{Rest}, negative if the rest has @code{direction} @code{DOWN}.")

 
 ;;;
 ;;; w
 ;;;
 
 ;;;
 ;;; w
 ;;;

-     (when ,ly:moment? "Global time step associated with this column
-happen?")
-     (whiteout ,boolean? "If true, the grob is printed over a white
-background to white-out underlying material, if the grob is visible.
- Usually #f by default.")
+     (when ,ly:moment? "Global time step associated with this column.")
+     (whiteout ,boolean-or-number? "If a number or true, the grob is
+printed over a white background to white-out underlying material, if
+the grob is visible.  A number indicates how far the white background
+extends beyond the bounding box of the grob as a multiple of the
+staff-line thickness.  The shape of the background is determined by
+@code{whiteout-style}.  Usually @code{#f} by default.")
+     (whiteout-style ,symbol? "Determines the shape of the
+@code{whiteout} background.  Available are @code{'outline},
+@code{'rounded-box}, and the default @code{'box}.")

      (width ,ly:dimension? "The width of a grob measured in staff
 space.")
      (word-space ,ly:dimension? "Space to insert between words in
      (width ,ly:dimension? "The width of a grob measured in staff
 space.")
      (word-space ,ly:dimension? "Space to insert between words in


@@ -1011,6 +1166,8 @@ texts.")
 ;;;
 ;;; x
 ;;;
 ;;;
 ;;; x
 ;;;

+     (X-align-on-main-noteheads ,boolean? "If true, this grob will
+ignore suspended noteheads when aligning itself on NoteColumn.")

      (X-extent ,number-pair? "Extent (size) in the X@tie{}direction,
 measured in staff-space units, relative to object's reference point.")
      (X-offset ,number? "The horizontal amount that this object is
      (X-extent ,number-pair? "Extent (size) in the X@tie{}direction,
 measured in staff-space units, relative to object's reference point.")
      (X-offset ,number? "The horizontal amount that this object is


@@ -1125,10 +1282,13 @@ empty in a particular staff, then that staff is erased.")
      (keep-alive-with ,ly:grob-array? "An array of other
 @code{VerticalAxisGroup}s.  If any of them are alive, then we will stay alive.")
 
      (keep-alive-with ,ly:grob-array? "An array of other
 @code{VerticalAxisGroup}s.  If any of them are alive, then we will stay alive.")
 

-     (left-items ,ly:grob-array? "DOCME")
+     (left-items ,ly:grob-array? "Grobs organized on the left by a spacing
+object.")

      (left-neighbor ,ly:grob? "The right-most column that has a spacing-wish
 for this column.")
 
      (left-neighbor ,ly:grob? "The right-most column that has a spacing-wish
 for this column.")
 

+     (make-dead-when ,ly:grob-array? "An array of other
+@code{VerticalAxisGroup}s.  If any of them are alive, then we will turn dead.")

      (melody-spanner ,ly:grob? "The @code{MelodyItem} object for a stem.")
      (minimum-translations-alist ,list? "An list of translations for a given
 start and end point.")
      (melody-spanner ,ly:grob? "The @code{MelodyItem} object for a stem.")
      (minimum-translations-alist ,list? "An list of translations for a given
 start and end point.")


@@ -1142,8 +1302,6 @@ pure-from-neighbor-interface to determine various grob heights.")
      (note-heads ,ly:grob-array? "An array of note head grobs.")
      (pedal-text ,ly:grob? "A pointer to the text of a mixed-style piano
 pedal.")
      (note-heads ,ly:grob-array? "An array of note head grobs.")
      (pedal-text ,ly:grob? "A pointer to the text of a mixed-style piano
 pedal.")

-     (potential-X-colliding-grobs ,ly:grob-array? "Grobs that can potentially
-collide with a self-aligned grob on the X-axis.")

      (pure-relevant-grobs ,ly:grob-array? "All the grobs (items and spanners)
 that are relevant for finding the @code{pure-Y-extent}")
      (pure-relevant-items ,ly:grob-array? "A subset of elements that are
      (pure-relevant-grobs ,ly:grob-array? "All the grobs (items and spanners)
 that are relevant for finding the @code{pure-Y-extent}")
      (pure-relevant-items ,ly:grob-array? "A subset of elements that are


@@ -1156,13 +1314,18 @@ relevant for finding the @code{pure-Y-extent}.")
      (rest ,ly:grob? "A pointer to a @code{Rest} object.")
      (rest-collision ,ly:grob? "A rest collision that a rest is in.")
      (rests ,ly:grob-array? "An array of rest objects.")
      (rest ,ly:grob? "A pointer to a @code{Rest} object.")
      (rest-collision ,ly:grob? "A rest collision that a rest is in.")
      (rests ,ly:grob-array? "An array of rest objects.")

-     (right-items ,ly:grob-array? "DOCME")
+     (right-items ,ly:grob-array? "Grobs organized on the right by
+a spacing object.")

      (right-neighbor ,ly:grob? "See @code{left-neighbor}.")
 
      (right-neighbor ,ly:grob? "See @code{left-neighbor}.")
 

+     (scripts ,ly:grob-array? "An array of @code{Script} objects.")

      (side-support-elements ,ly:grob-array? "The side support, an array of
 grobs.")
      (slur ,ly:grob? "A pointer to a @code{Slur} object.")
      (spacing ,ly:grob? "The spacing spanner governing this section.")
      (side-support-elements ,ly:grob-array? "The side support, an array of
 grobs.")
      (slur ,ly:grob? "A pointer to a @code{Slur} object.")
      (spacing ,ly:grob? "The spacing spanner governing this section.")

+     (space-increment ,ly:dimension? "The amount by which the total duration
+of a multimeasure rest affects horizontal spacing.  Each doubling of the
+duration adds @code{space-increment} to the length of the bar.")

      (spacing-wishes ,ly:grob-array? "An array of note spacing or staff spacing
 objects.")
      (span-start ,boolean? "Is the note head at the start of a spanner?")
      (spacing-wishes ,ly:grob-array? "An array of note spacing or staff spacing
 objects.")
      (span-start ,boolean? "Is the note head at the start of a spanner?")


@@ -1190,10 +1353,6 @@ results, use @code{LEFT} and @code{RIGHT}.")
      (vertical-skyline-elements ,ly:grob-array? "An array of grobs
 used to create vertical skylines.")
 
      (vertical-skyline-elements ,ly:grob-array? "An array of grobs
 used to create vertical skylines.")
 

-     (X-colliding-grobs ,ly:grob-array? "Grobs that can collide
-with a self-aligned grob on the X-axis.")
-     (Y-colliding-grobs ,ly:grob-array? "Grobs that can collide
-with a self-aligned grob on the Y-axis.")

      (X-common ,ly:grob? "Common reference point for axis group.")
      (Y-common ,ly:grob? "See @code{X-common}.")
 
      (X-common ,ly:grob? "Common reference point for axis group.")
      (Y-common ,ly:grob? "See @code{X-common}.")
 


@@ -1257,7 +1416,8 @@ to be within staff spaces.")
      (quantized-positions ,number-pair? "The beam positions after
 quanting.")
 
      (quantized-positions ,number-pair? "The beam positions after
 quanting.")
 

-
+     (script-column ,ly:grob? "A @code{ScriptColumn} associated with a
+@code{Script} object.")

      (script-stencil ,pair? "A pair @code{(@var{type} . @var{arg})} which
 acts as an index for looking up a @code{Stencil} object.")
      (shorten ,ly:dimension? "The amount of space that a stem is shortened.
      (script-stencil ,pair? "A pair @code{(@var{type} . @var{arg})} which
 acts as an index for looking up a @code{Stencil} object.")
      (shorten ,ly:dimension? "The amount of space that a stem is shortened.