Bring dev/johngourlay/issue-4751 up to date with respect to staging.

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

diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index 5b7f86e8528b760bd3e9f6ad02e7f7e118d214af..60b9d5b000c2e6896237aac6c9404857610719ac 100644 (file)
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -214,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.1} and @code{1.0}
-(continuous line).  If set to @code{0.0}, a dotted line is produced")
+@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


@@ -530,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?")


@@ -572,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


@@ -607,9 +615,6 @@ visual output is influenced by changes to
 ;;;
      (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


@@ -703,6 +708,11 @@ 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}.")
 
      (number-type ,symbol? "Numbering style. Choices include
 @code{roman-lower}, @code{roman-upper} and @code{arabic}.")
 


@@ -774,6 +784,10 @@ 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.")
 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


@@ -844,6 +858,9 @@ value @w{@code{-1}} means left aligned, @code{0}@tie{}centered, and
 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.")
 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.")

+     (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


@@ -871,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


@@ -1130,9 +1148,15 @@ one below this grob.")
 ;;; w
 ;;;
      (when ,ly:moment? "Global time step associated with this column.")
 ;;; w
 ;;;
      (when ,ly:moment? "Global time step associated with this column.")

-     (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.")
+     (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


@@ -1258,7 +1282,8 @@ 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.")
 


@@ -1289,7 +1314,8 @@ 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}.")
 
      (scripts ,ly:grob-array? "An array of @code{Script} objects.")
      (right-neighbor ,ly:grob? "See @code{left-neighbor}.")
 
      (scripts ,ly:grob-array? "An array of @code{Script} objects.")