Fix 917.

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

diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index 65fb09c4b4cf0722dac160814f9a121964825a08..cfa8726c48079a75b4064fe2af06c720e6c18b40 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--2010  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))


@@ -27,6 +38,10 @@
 ;;
      (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,


@@ -95,6 +110,10 @@ 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


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

      (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


@@ -262,9 +285,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}.")


@@ -451,6 +474,12 @@ 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.")

 
 
 ;;
 
 
 ;;


@@ -556,6 +585,25 @@ 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.")


@@ -563,6 +611,11 @@ syllable following an extender).")
 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-affinity-spacing ,list? "An alist of spacing variables
+that controls the spacing from a loose line (see @var{staff-affinity})
+to the staff for which the loose line does not have affinity.
+See @var{next-staff-spacing} for a description of the elements of
+this alist.")

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


@@ -703,6 +756,8 @@ duration.  Typically, the width of a note head.  See also
      (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-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


@@ -751,8 +806,6 @@ should use @code{LEFT}.")
      (thickness ,number? "Line thickness, generally measured in
 @code{line-thickness}.")
      (thin-kern ,number? "The space after a hair-line in a bar line.")
      (thickness ,number? "Line thickness, generally measured in
 @code{line-thickness}.")
      (thin-kern ,number? "The space after a hair-line in a bar line.")

-     (threshold ,number-pair? "@code{(@var{min} . @var{max})}, where
-@var{min} and @var{max} are dimensions in staff space.")

      (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


@@ -792,6 +845,8 @@ 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.  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


@@ -847,8 +902,8 @@ constructed from a whole number of squiggles.")
      (accidental-grob ,ly:grob? "The accidental for this note.")
      (accidental-grobs ,list? "An alist with @code{(@var{notename} .
 @var{groblist})} entries.")
      (accidental-grob ,ly:grob? "The accidental for this note.")
      (accidental-grobs ,list? "An alist with @code{(@var{notename} .
 @var{groblist})} entries.")

-     (adjacent-hairpins ,ly:grob-array? "An array of directly neighboring
-hairpins.")
+     (adjacent-spanners ,ly:grob-array? "An array of directly neighboring
+dynamic spanners.")

      (all-elements ,ly:grob-array? "An array of all grobs in this line.  Its
 function is to protect objects from being garbage collected.")
      (arpeggio ,ly:grob? "A pointer to an @code{Arpeggio} object.")
      (all-elements ,ly:grob-array? "An array of all grobs in this line.  Its
 function is to protect objects from being garbage collected.")
      (arpeggio ,ly:grob? "A pointer to an @code{Arpeggio} object.")


@@ -886,11 +941,8 @@ in addition to notes and stems.")
 empty in a particular staff, then that staff is erased.")
 
      (left-items ,ly:grob-array? "DOCME")
 empty in a particular staff, then that staff is erased.")
 
      (left-items ,ly:grob-array? "DOCME")

-     (left-neighbors ,ly:grob-array? "An array of @code{spacing-wishes} grobs
-that are close to the current column.
-
-The closest @code{spacing-wishes} determine the actual distances between the
-columns.")
+     (left-neighbor ,ly:grob? "The right-most column that has a spacing-wish
+for this column.")

 
      (normal-stems ,ly:grob-array? "An array of visible stems.")
      (note-columns ,ly:grob-array? "An array of @code{NoteColumn} grobs.")
 
      (normal-stems ,ly:grob-array? "An array of visible stems.")
      (note-columns ,ly:grob-array? "An array of @code{NoteColumn} grobs.")


@@ -909,10 +961,8 @@ relevant for finding the @code{pure-Y-extent}.")
      (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")
      (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-neighbors ,ly:grob-array? "See @code{left-neighbors}.")
+     (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.")


@@ -921,6 +971,7 @@ 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.")

+     (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.")
      (stems ,ly:grob-array? "An array of stem objects.")
      (staff-symbol ,ly:grob? "The staff symbol grob that we are in.")
      (stem ,ly:grob? "A pointer to a @code{Stem} object.")
      (stems ,ly:grob-array? "An array of stem objects.")


@@ -966,6 +1017,8 @@ supported by this object.  It is initialized from the @code{meta} field.")
 
      (least-squares-dy ,number? "The ideal beam slope, without damping.")
 
 
      (least-squares-dy ,number? "The ideal beam slope, without damping.")
 

+     (maybe-loose ,boolean? "Used to mark a breakable column that is
+loose if and only if it is in the middle of a line.")

      (meta ,list? "Provide meta information.  It is an alist with the
 entries @code{name} and @code{interfaces}.")
      (minimum-distances ,list? "A list of rods that have the format
      (meta ,list? "Provide meta information.  It is an alist with the
 entries @code{name} and @code{interfaces}.")
      (minimum-distances ,list? "A list of rods that have the format


@@ -991,6 +1044,8 @@ 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.")
      (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.")

 
      (use-breve-rest ,boolean? "Use breve rests for measures longer
 than a whole rest.")
 
      (use-breve-rest ,boolean? "Use breve rests for measures longer
 than a whole rest.")


@@ -1033,8 +1088,6 @@ ligature grob in (in @code{staff-space} units).")
 
      (inclinatum ,boolean? "Is this neume an inclinatum?")
 
 
      (inclinatum ,boolean? "Is this neume an inclinatum?")
 

-     (join-heads ,boolean? "Whether to join the note heads of an ambitus
-grob with a vertical line.")

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