Web: mention Linux Magazine article.

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

diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index b9cf4ed3a20ff876816b9ff1bfca70cfaf86fffb..3381cb9e27ed2858ea1decc3e88b31e4c1d5b97f 100644 (file)
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -1,9 +1,20 @@
-;;;; define-grob-properties.scm -- part of generated backend documentation
+;;;; This file is part of LilyPond, the GNU music typesetter.

 ;;;;
 ;;;;

-;;;;  source file of the GNU LilyPond music typesetter
-;;;;
-;;;; (c) 1998--2009  Han-Wen Nienhuys <hanwen@xs4all.nl>
+;;;; Copyright (C) 1998--2011  Han-Wen Nienhuys <hanwen@xs4all.nl>

 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>

+;;;;
+;;;; LilyPond is free software: you can redistribute it and/or modify
+;;;; it under the terms of the GNU General Public License as published by
+;;;; the Free Software Foundation, either version 3 of the License, or
+;;;; (at your option) any later version.
+;;;;
+;;;; LilyPond is distributed in the hope that it will be useful,
+;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;;; GNU General Public License for more details.
+;;;;
+;;;; You should have received a copy of the GNU General Public License
+;;;; along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.

 
 (define (define-grob-property symbol type? description)
   (if (not (equal? (object-property symbol 'backend-doc) #f))
 
 (define (define-grob-property symbol type? description)
   (if (not (equal? (object-property symbol 'backend-doc) #f))


@@ -14,9 +25,7 @@
   symbol)
 
 ;; put this in an alist?
   symbol)
 
 ;; put this in an alist?

-(define-public
-  all-user-grob-properties
-
+(define-public all-user-grob-properties

   (map
    (lambda (x)
      (apply define-grob-property x))
   (map
    (lambda (x)
      (apply define-grob-property x))


@@ -27,10 +36,6 @@
 ;;
      (add-stem-support ,boolean? "If set, the @code{Stem} object is
 included in this script's support.")
 ;;
      (add-stem-support ,boolean? "If set, the @code{Stem} object is
 included in this script's support.")

-     (after-last-staff-spacing ,list? "An alist of spacing variables
-that controls the spacing after the last staff in this staff group.
-See @var{next-staff-spacing} for a description of the elements of
-this alist.")

      (after-line-breaking ,boolean? "Dummy property, used to trigger
 callback for @code{after-line-breaking}.")
      (align-dir ,ly:dir? "Which side to align? @code{-1}: left side,
      (after-line-breaking ,boolean? "Dummy property, used to trigger
 callback for @code{after-line-breaking}.")
      (align-dir ,ly:dir? "Which side to align? @code{-1}: left side,


@@ -43,6 +48,9 @@ be created below this bar line.")
      (alteration-alist ,list? "List of @code{(@var{pitch}
 . @var{accidental})} pairs for key signature.")
      (annotation ,string? "Annotate a grob for debug purposes.")
      (alteration-alist ,list? "List of @code{(@var{pitch}
 . @var{accidental})} pairs for key signature.")
      (annotation ,string? "Annotate a grob for debug purposes.")

+     (annotation-balloon ,boolean? "Print the balloon around an annotation.")
+     (annotation-line ,boolean? "Print the line from an annotation to the
+grob that it annotates.")

      (arpeggio-direction ,ly:dir? "If set, put an arrow on the
 arpeggio squiggly line.")
      (arrow-length ,number? "Arrow length.")
      (arpeggio-direction ,ly:dir? "If set, put an arrow on the
 arpeggio squiggly line.")
      (arrow-length ,number? "Arrow length.")


@@ -70,7 +78,6 @@ grobs, this should contain only one number.")
 ;;
 ;; b
 ;;
 ;;
 ;; b
 ;;

-     (bar-size ,ly:dimension? "The size of a bar line.")

      (base-shortest-duration ,ly:moment? "Spacing is based on the
 shortest notes in a piece.  Normally, pieces are spaced as if notes at
 least as short as this are present.")
      (base-shortest-duration ,ly:moment? "Spacing is based on the
 shortest notes in a piece.  Normally, pieces are spaced as if notes at
 least as short as this are present.")


@@ -99,10 +106,6 @@ beamlet, as a proportion of the distance between two adjacent stems.")
      (before-line-breaking ,boolean? "Dummy property, used to trigger
 a callback function.")
      (between-cols ,pair? "Where to attach a loose column to.")
      (before-line-breaking ,boolean? "Dummy property, used to trigger
 a callback function.")
      (between-cols ,pair? "Where to attach a loose column to.")

-     (between-staff-spacing ,list? "An alist of spacing variables
-that controls the spacing between staves within this staff group.
-See @var{next-staff-spacing} for a description of the elements of
-this alist.")

      (bound-details ,list? "An alist of properties for determining
 attachments of spanners to edges.")
      (bound-padding ,number? "The amount of padding to insert around
      (bound-details ,list? "An alist of properties for determining
 attachments of spanners to edges.")
      (bound-padding ,number? "The amount of padding to insert around


@@ -167,6 +170,10 @@ hairpins (al/del niente).")
 edges of beams?")
      (collapse-height ,ly:dimension? "Minimum height of system start
 delimiter.  If equal or smaller, the bracket/brace/line is removed.")
 edges of beams?")
      (collapse-height ,ly:dimension? "Minimum height of system start
 delimiter.  If equal or smaller, the bracket/brace/line is removed.")

+     (collision-interfaces ,list? "A list of interfaces for which
+automatic beam-collision resolution is run.")
+     (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.")
      (common-shortest-duration ,ly:moment? "The most common shortest
 note length.  This is used in spacing.  Enlarging this sets the score
      (color ,color? "The color of this grob.")
      (common-shortest-duration ,ly:moment? "The most common shortest
 note length.  This is used in spacing.  Enlarging this sets the score


@@ -181,7 +188,6 @@ this grob looks as a continued break.")
 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.")
 
 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.")
 

-

 ;;
 ;; d
 ;;
 ;;
 ;; d
 ;;


@@ -196,10 +202,11 @@ an ending t-value, a @code{dash-fraction}, and a @code{dash-period}.")
 whitespace.  If negative, no line is drawn at all.")
      (default-direction ,ly:dir? "Direction determined by note head
 positions.")
 whitespace.  If negative, no line is drawn at all.")
      (default-direction ,ly:dir? "Direction determined by note head
 positions.")

-     (default-next-staff-spacing ,list? "An alist of spacing variables
-that controls the spacing between this staff and the next.
-See @var{next-staff-spacing} for a description of the elements of
-this alist.")
+     (default-staff-staff-spacing ,list? "The settings to use for
+@code{staff-staff-spacing} when it is unset, for ungrouped staves
+and for grouped staves that do not have the relevant
+@code{StaffGrouper} property set (@code{staff-staff-spacing} or
+@code{staffgroup-staff-spacing}).")

      (details ,list? "Alist of parameters for detailed grob behavior.
 More information on the allowed parameters for a grob can be found by
 looking at the top of the Internals Reference page for each interface
      (details ,list? "Alist of parameters for detailed grob behavior.
 More information on the allowed parameters for a grob can be found by
 looking at the top of the Internals Reference page for each interface


@@ -274,9 +281,9 @@ for standard flags, @code{'mensural} and @code{'no-flag}, which
 switches off the flag.")
      (font-encoding ,symbol? "The font encoding is the broadest
 category for selecting a font.  Currently, only lilypond's system
 switches off the flag.")
      (font-encoding ,symbol? "The font encoding is the broadest
 category for selecting a font.  Currently, only lilypond's system

-fonts (Emmentaler and Aybabtu) are using this property.  Available
-values are @code{fetaMusic} (Emmentaler), @code{fetaBraces} (Aybabtu),
-@code{fetaNumber} (Emmentaler), and @code{fetaDynamic} (Emmentaler).")
+fonts (Emmentaler) are using this property.  Available
+values are @code{fetaMusic} (Emmentaler), @code{fetaBraces},
+@code{fetaText} (Emmentaler).")

      (font-family ,symbol? "The font family is the broadest category
 for selecting text fonts.  Options include: @code{sans},
 @code{roman}.")
      (font-family ,symbol? "The font family is the broadest category
 for selecting text fonts.  Options include: @code{sans},
 @code{roman}.")


@@ -292,6 +299,7 @@ include @code{upright}, @code{italic}, @code{caps}.")
 @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.")
 @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.")

+     (footnote-text ,markup? "A footnote for the grob.")

      (force-hshift ,number? "This specifies a manual shift for notes
 in collisions.  The unit is the note head width of the first voice
 note.  This is used by @rinternals{note-collision-interface}.")
      (force-hshift ,number? "This specifies a manual shift for notes
 in collisions.  The unit is the note head width of the first voice
 note.  This is used by @rinternals{note-collision-interface}.")


@@ -332,6 +340,10 @@ Default @code{none} for markup fret diagrams, @code{below-string} for
 @item
 @code{fret-count} -- The number of frets.  Default@tie{}4.
 @item
 @item
 @code{fret-count} -- The number of frets.  Default@tie{}4.
 @item

+@code{fret-label-custom-format} -- The format string to be used label
+the lowest fret number, when @code{number-type} equals to
+@code{custom}.  Default@tie{}\"~a\".
+@item

 @code{fret-label-font-mag} -- The magnification of the font used to
 label the lowest fret number.  Default@tie{}0.5.
 @item
 @code{fret-label-font-mag} -- The magnification of the font used to
 label the lowest fret number.  Default@tie{}0.5.
 @item


@@ -347,7 +359,9 @@ Default@tie{}0.
 string.  Default @code{\"x\"}.
 @item
 @code{number-type} -- Type of numbers to use in fret label.  Choices
 string.  Default @code{\"x\"}.
 @item
 @code{number-type} -- Type of numbers to use in fret label.  Choices

-include @code{roman-lower}, @code{roman-upper}, and @code{arabic}.
+include @code{roman-lower}, @code{roman-upper}, @code{arabic} and
+@code{custom}.  In the later case, the format string is supplied by
+the @code{fret-label-custom-format} property.

 Default @code{roman-lower}.
 @item
 @code{open-string} -- Character string to be used to indicate open
 Default @code{roman-lower}.
 @item
 @code{open-string} -- Character string to be used to indicate open


@@ -400,6 +414,7 @@ typeset.  Valid choices depend on the function that is reading this
 property.")
      (glyph-name ,string? "The glyph name within the font.")
      (glyph-name-alist ,list? "An alist of key-string pairs.")
 property.")
      (glyph-name ,string? "The glyph name within the font.")
      (glyph-name-alist ,list? "An alist of key-string pairs.")

+     (graphical ,boolean? "Display in graphical (vs. text) form.")

      (grow-direction ,ly:dir? "Crescendo or decrescendo?")
 
 
      (grow-direction ,ly:dir? "Crescendo or decrescendo?")
 
 


@@ -463,20 +478,11 @@ resolution on this @code{NoteColumn}.")
 configuration to this index, and print the respective scores.")
      (inspect-quants ,number-pair? "If debugging is set, set beam and
 slur quants to this position, and print the respective scores.")
 configuration to this index, and print the respective scores.")
      (inspect-quants ,number-pair? "If debugging is set, set beam and
 slur quants to this position, and print the respective scores.")

-     (inter-loose-line-spacing ,list? "Specifies how to vertically
-position a non-spaced line relative to the other non-spaced lines
-around it.  See @var{next-staff-spacing} for the format of this list.")
-     (inter-staff-spacing ,list? "Specifies how to vertically
-position a non-spaced line relative to the staff for which it
-has affinity.  See @var{next-staff-spacing} for the format of this list.")

 
 
 ;;
 ;; k
 ;;
 
 
 ;;
 ;; k
 ;;

-     (keep-fixed-while-stretching ,boolean? "A grob with this property
-set to true is fixed relative to the staff above it when systems are
-stretched.")

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


@@ -491,9 +497,11 @@ correction and @code{1} for full correction.")
 ;; l
 ;;
      (labels ,list? "List of labels (symbols) placed on a column.")
 ;; l
 ;;
      (labels ,list? "List of labels (symbols) placed on a column.")

-     (layer ,integer? "The output layer (a value between 0
-and@tie{}2): Layers define the order of printing objects.  Objects in
-lower layers are overprinted by objects in higher layers.")
+     (layer ,integer? "An integer which determines the order of printing
+objects.  Objects with the lowest value of layer are drawn first, then
+objects with progressively higher values are drawn, so objects with
+higher values overwrite objects with lower values.  By default most
+objects are assigned a layer value of 1.")

      (ledger-line-thickness ,number-pair? "The thickness of ledger
 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
      (ledger-line-thickness ,number-pair? "The thickness of ledger
 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


@@ -501,7 +509,7 @@ are added.")
      (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

-left to an object (e.g., a group of accidentals).")
+left to an object (e.g., a lyric extender).")

      (length ,ly:dimension? "User override for the stem length of
 unbeamed stems.")
      (length-fraction ,number? "Multiplier for lengths.  Used for
      (length ,ly:dimension? "User override for the stem length of
 unbeamed stems.")
      (length-fraction ,number? "Multiplier for lengths.  Used for


@@ -574,25 +582,6 @@ center of the staff.")
 to flip the direction of custos stem.")
      (next ,ly:grob? "Object that is next relation (e.g., the lyric
 syllable following an extender).")
 to flip the direction of custos stem.")
      (next ,ly:grob? "Object that is next relation (e.g., the lyric
 syllable following an extender).")

-     (next-staff-spacing ,list? "An alist of properties used to position
-the next staff in the system.  The symbols that can be defined in the alist
-are
-@itemize @bullet
-@item @var{space} -- the amount of stretchable space between the center
-of this staff and the center of the next staff;
-@item @var{padding} -- the minimum amount of whitespace that must be
-present between this staff and the next staff;
-@item @var{stretchability} -- the ease with which the stretchable
-space increases when the system to which this staff belongs is stretched.
-If this is zero, the distance to the next staff will be fixed either at
-@var{space} or at @var{padding} plus the minimum distance to ensure
-there is no overlap, whichever is larger;
-@item @var{minimum-distance} -- the minimum distance to place between
-the center of this staff and the center of the next. This differs
-from @var{padding} in that the height of a staff has no effect on
-the application of @var{minimum-distance} (whereas the height of a
-staff is crucial for @var{padding}).
-@end itemize")

      (no-alignment ,boolean? "If set, don't place this grob in a
 @code{VerticalAlignment}; rather, place it using its own
 @code{Y-offset} callback.")
      (no-alignment ,boolean? "If set, don't place this grob in a
 @code{VerticalAlignment}; rather, place it using its own
 @code{Y-offset} callback.")


@@ -600,9 +589,39 @@ staff is crucial for @var{padding}).
 object.")
      (no-stem-extend ,boolean? "If set, notes with ledger lines do not
 get stems extending to the middle staff line.")
 object.")
      (no-stem-extend ,boolean? "If set, notes with ledger lines do not
 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-musical ,boolean? "True if the grob belongs to a
 @code{NonMusicalPaperColumn}.")
      (non-default ,boolean? "Set for manually specified clefs.")
      (non-musical ,boolean? "True if the grob belongs to a
 @code{NonMusicalPaperColumn}.")

+     (nonstaff-nonstaff-spacing ,list? "The spacing alist
+controlling the distance between the current non-staff line and
+the next non-staff line in the direction of @code{staff-affinity},
+if both are on the same side of the related staff, and
+@code{staff-affinity} is either @code{UP} or @code{DOWN}.  See
+@code{staff-staff-spacing} for a description of the alist
+structure.")
+     (nonstaff-relatedstaff-spacing ,list? "The spacing alist
+controlling the distance between the current non-staff line and
+the nearest staff in the direction of @code{staff-affinity}, if
+there are no non-staff lines between the two, and
+@code{staff-affinity} is either @code{UP} or @code{DOWN}.  If
+@code{staff-affinity} is @code{CENTER}, then
+@code{nonstaff-relatedstaff-spacing} is used for the nearest
+staves on @emph{both} sides, even if other non-staff lines appear
+between the current one and either of the staves.  See
+@code{staff-staff-spacing} for a description of the alist
+structure.")
+     (nonstaff-unrelatedstaff-spacing ,list? "The spacing alist
+controlling the distance between the current non-staff line and
+the nearest staff in the opposite direction from
+@code{staff-affinity}, if there are no other non-staff lines
+between the two, and @code{staff-affinity} is either @code{UP} or
+@code{DOWN}.  See @code{staff-staff-spacing} for a description of
+the alist structure.")
+     (normalized-endpoints ,pair? "Represents left and right placement
+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.")
 
      (note-names ,vector? "Vector of strings containing names for
 easy-notation note heads.")
 


@@ -718,6 +737,11 @@ vertical distance between two staves, it is possible to have a
 configuration which would result in a tight interleaving of grobs from
 the top staff and the bottom staff.  The larger this parameter is, the
 farther apart the staves are placed in such a configuration.")
 configuration which would result in a tight interleaving of grobs from
 the top staff and the bottom staff.  The larger this parameter is, the
 farther apart the staves are placed in such a configuration.")

+     (skyline-vertical-padding ,number? "The amount by which the left
+and right skylines of a column are padded vertically, beyond the
+@code{Y-extent}s and @code{extra-spacing-height}s of the constituent
+grobs in the column.  Increase this to prevent interleaving of grobs
+from adjacent columns.")

      (slash-negative-kern ,number? "The space to remove between
 slashes in percent repeat glyphs.  Larger values bring the two
 elements closer together.")
      (slash-negative-kern ,number? "The space to remove between
 slashes in percent repeat glyphs.  Larger values bring the two
 elements closer together.")


@@ -737,11 +761,27 @@ there.")
      (spacing-increment ,number? "Add this much space for a doubled
 duration.  Typically, the width of a note head.  See also
 @rinternals{spacing-spanner-interface}.")
      (spacing-increment ,number? "Add this much space for a doubled
 duration.  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.
+
+For example, a @code{MultiMeasureRest} will ignore prefatory items at its
+bounds (i.e., clefs, key signatures and time signatures) using the following
+override:
+
+@example
+\\override MultiMeasureRest #'spacing-pair = #'(staff-bar . staff-bar)
+@end example")

      (springs-and-rods ,boolean? "Dummy variable for triggering
 spacing routines.")
      (stacking-dir ,ly:dir? "Stack objects in which direction?")
      (springs-and-rods ,boolean? "Dummy variable for triggering
 spacing routines.")
      (stacking-dir ,ly:dir? "Stack objects in which direction?")

-     (staff-affinity ,ly:dir? "The direction of the staff to which this
-line should stick.")
+     (staff-affinity ,ly:dir? "The direction of the staff to use
+for spacing the current non-staff line.  Choices are @code{UP},
+@code{DOWN}, and @code{CENTER}.  If @code{CENTER}, the non-staff
+line will be placed equidistant between the two nearest staves on
+either side, unless collisions or other spacing constraints
+prevent this.  Setting @code{staff-affinity} for a staff causes it
+to be treated as a non-staff line.  Setting @code{staff-affinity}
+to @code{#f} causes a non-staff line to be treated as a staff.")

      (staff-padding ,ly:dimension? "Maintain this much space between
 reference points and the staff.  Its effect is to align objects of
 differing sizes (like the dynamics @b{p} and @b{f}) on their
      (staff-padding ,ly:dimension? "Maintain this much space between
 reference points and the staff.  Its effect is to align objects of
 differing sizes (like the dynamics @b{p} and @b{f}) on their


@@ -750,6 +790,48 @@ baselines.")
 staff spaces, counted from the middle line.")
      (staff-space ,ly:dimension? "Amount of space between staff lines,
 expressed in global @code{staff-space}.")
 staff spaces, counted from the middle line.")
      (staff-space ,ly:dimension? "Amount of space between staff lines,
 expressed in global @code{staff-space}.")

+     (staff-staff-spacing ,list? "When applied to a staff-group's
+@code{StaffGrouper} grob, this spacing alist controls the distance
+between consecutive staves within the staff-group.  When applied
+to a staff's @code{VerticalAxisGroup} grob, it controls the
+distance between the staff and the nearest staff below it in the
+same system, replacing any settings inherited from the
+@code{StaffGrouper} grob of the containing staff-group, if there
+is one.  This property remains in effect even when non-staff lines
+appear between staves.  The alist can contain the following keys:
+
+@itemize
+
+@item
+@code{basic-distance} -- the vertical distance, measured in
+staff-spaces, between the reference points of the two items when
+no collisions would result, and no stretching or compressing is in
+effect.
+
+@item
+@code{minimum-distance} -- the smallest allowable vertical
+distance, measured in staff-spaces, between the reference points
+of the two items, when compressing is in effect.
+
+@item
+@code{padding} -- the minimum required amount of unobstructed
+vertical whitespace between the bounding boxes (or skylines) of
+the two items, measured in staff-spaces.
+
+@item
+@code{stretchability} -- a unitless measure of the dimension's
+relative propensity to stretch.  If zero, the distance will not
+stretch (unless collisions would result).
+
+@end itemize")
+     (staffgroup-staff-spacing ,list? "The spacing alist
+controlling the distance between the last staff of the current
+staff-group and the staff just below it in the same system, even
+if one or more non-staff lines exist between the two staves.  If
+the @code{staff-staff-spacing} property of the staff's
+@code{VerticalAxisGroup} grob is set, that is used instead.  See
+@code{staff-staff-spacing} for a description of the alist
+structure.")

      (stem-attachment ,number-pair? "An @code{(@var{x} . @var{y})}
 pair where the stem attaches to the notehead.")
      (stem-end-position ,number? "Where does the stem end (the end is
      (stem-attachment ,number-pair? "An @code{(@var{x} . @var{y})}
 pair where the stem attaches to the notehead.")
      (stem-end-position ,number? "Where does the stem end (the end is


@@ -829,6 +911,9 @@ one below this grob.")
 ;;
      (when ,ly:moment? "Global time step associated with this column
 happen?")
 ;;
      (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.")

      (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


@@ -902,9 +987,12 @@ bounds are spaced.")
      (columns ,ly:grob-array? "An array of grobs, typically containing
 @code{PaperColumn} or @code{NoteColumn} objects.")
      (conditional-elements ,ly:grob-array? "Internal use only.")
      (columns ,ly:grob-array? "An array of grobs, typically containing
 @code{PaperColumn} or @code{NoteColumn} objects.")
      (conditional-elements ,ly:grob-array? "Internal use only.")

+     (covered-grobs ,ly:grob-array? "Grobs that could potentially collide
+with a beam.")

 
      (direction-source ,ly:grob? "In case @code{side-relative-direction} is
 set, which grob to get the direction from.")
 
      (direction-source ,ly:grob? "In case @code{side-relative-direction} is
 set, which grob to get the direction from.")

+     (display-cautionary ,boolean? "Should the grob be displayed as a cautionary grob?")

      (dot ,ly:grob? "A reference to a @code{Dots} object.")
      (dots ,ly:grob-array? "Multiple @code{Dots} objects.")
 
      (dot ,ly:grob? "A reference to a @code{Dots} object.")
      (dots ,ly:grob-array? "Multiple @code{Dots} objects.")
 


@@ -922,6 +1010,9 @@ in addition to notes and stems.")
      (items-worth-living ,ly:grob-array? "An array of interesting items.  If
 empty in a particular staff, then that staff is erased.")
 
      (items-worth-living ,ly:grob-array? "An array of interesting items.  If
 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.")
+

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


@@ -932,6 +1023,8 @@ for this column.")
      (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.")

+     (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
 relevant for finding the @code{pure-Y-extent}.")
      (pure-relevant-spanners ,ly:grob-array? "A subset of elements that are
      (pure-relevant-items ,ly:grob-array? "A subset of elements that are
 relevant for finding the @code{pure-Y-extent}.")
      (pure-relevant-spanners ,ly:grob-array? "A subset of elements that are


@@ -945,16 +1038,18 @@ relevant for finding the @code{pure-Y-extent}.")
      (right-items ,ly:grob-array? "DOCME")
      (right-neighbor ,ly:grob? "See @code{left-neighbor}.")
 
      (right-items ,ly:grob-array? "DOCME")
      (right-neighbor ,ly:grob? "See @code{left-neighbor}.")
 

-     (separation-item ,ly:grob? "A pointer to a @code{SeparationItem}
-object.")

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

-     (spaceable-staves ,ly:grob-array? "Objects to be spaced during page
-layout.")

      (spacing ,ly:grob? "The spacing spanner governing this section.")
      (spacing-wishes ,ly:grob-array? "An array of note spacing or staff spacing
 objects.")
      (spacing ,ly:grob? "The spacing spanner governing this section.")
      (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?")
+     (spanner-placement ,ly:dir? "The place of an annotation on a spanner.
+LEFT is for the first spanner, and RIGHT is for the last.  CENTER will
+place it on the broken spanner that falls closest to the center of the length
+of the entire spanner, although this behavior is unpredictable in situations
+with lots of rhythmic diversity.  For predictable results, use LEFT and RIGHT.")

      (staff-grouper ,ly:grob? "The staff grouper we belong to.")
      (staff-symbol ,ly:grob? "The staff symbol grob that we are in.")
      (stem ,ly:grob? "A pointer to a @code{Stem} object.")
      (staff-grouper ,ly:grob? "The staff grouper we belong to.")
      (staff-symbol ,ly:grob? "The staff symbol grob that we are in.")
      (stem ,ly:grob? "A pointer to a @code{Stem} object.")


@@ -972,7 +1067,7 @@ objects.")
      (adjacent-pure-heights ,pair? "A pair of vectors.  Used by a
 @code{VerticalAxisGroup} to cache the @code{Y-extent}s of different column
 ranges.")
      (adjacent-pure-heights ,pair? "A pair of vectors.  Used by a
 @code{VerticalAxisGroup} to cache the @code{Y-extent}s of different column
 ranges.")

-     
+

      (bar-extent ,number-pair? "The Y-extent of the actual bar line.
 This may differ from @code{Y-extent} because it does not include the dots in
 a repeat bar line.")
      (bar-extent ,number-pair? "The Y-extent of the actual bar line.
 This may differ from @code{Y-extent} because it does not include the dots in
 a repeat bar line.")


@@ -1013,9 +1108,6 @@ did its job.  This ensures that a positioning is only done once.")
      (pure-Y-extent ,number-pair? "The estimated height of a system.")
      (pure-Y-offset-in-progress ,boolean? "A debugging aid for catching
 cyclic dependencies.")
      (pure-Y-extent ,number-pair? "The estimated height of a system.")
      (pure-Y-offset-in-progress ,boolean? "A debugging aid for catching
 cyclic dependencies.")

-
-     (quant-score ,string? "The beam quanting score; stored for
-debugging.")

      (quantize-position ,boolean? "If set, a vertical alignment is aligned
 to be within staff spaces.")
      (quantized-positions ,number-pair? "The beam positions after
      (quantize-position ,boolean? "If set, a vertical alignment is aligned
 to be within staff spaces.")
      (quantized-positions ,number-pair? "The beam positions after


@@ -1025,8 +1117,6 @@ quanting.")
 acts as an index for looking up a @code{Stencil} object.")
      (shorten ,ly:dimension? "The amount of space that a stem is shortened.
 Internally used to distribute beam shortening over stems.")
 acts as an index for looking up a @code{Stencil} object.")
      (shorten ,ly:dimension? "The amount of space that a stem is shortened.
 Internally used to distribute beam shortening over stems.")

-     (skyline-distance ,number? "The distance between this staff and the
-next one, as determined by a skyline algorithm.")

      (stem-info ,pair? "A cache of stem parameters.")
      (system-Y-offset ,number? "The Y-offset (relative to the bottom of the
 top-margin of the page) of the system to which this staff belongs.")
      (stem-info ,pair? "A cache of stem parameters.")
      (system-Y-offset ,number? "The Y-offset (relative to the bottom of the
 top-margin of the page) of the system to which this staff belongs.")


@@ -1067,13 +1157,15 @@ right neighbour, encoded as a bit mask.")
 
      (flexa-height ,ly:dimension? "The height of a flexa shape in a ligature
 grob (in @code{staff-space} units).")
 
      (flexa-height ,ly:dimension? "The height of a flexa shape in a ligature
 grob (in @code{staff-space} units).")

+     (flexa-interval ,integer? "The interval spanned by the two notes of a
+flexa shape (1 is a second, 7 is an octave).")

      (flexa-width ,ly:dimension? "The width of a flexa shape in a
 ligature grob in (in @code{staff-space} units).")
      (flexa-width ,ly:dimension? "The width of a flexa shape in a
 ligature grob in (in @code{staff-space} units).")

+     (ligature-flexa ,boolean? "request joining note to the previous one
+in a flexa.")

 
      (inclinatum ,boolean? "Is this neume an inclinatum?")
 
 
      (inclinatum ,boolean? "Is this neume an inclinatum?")
 

-     (join-right-amount ,number? "A length used for calculating the
-Y-extent of mensural ligatures.")

 
      (linea ,boolean? "Attach vertical lines to this neume?")
 
 
      (linea ,boolean? "Attach vertical lines to this neume?")