Merge commit 'origin' into beamlets2

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

diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index 49916fa24ee62543ad408489d2db41e59cfd67ed..9ed32e95a27753ab9b77dae6b24aa465e0ee7164 100644 (file)
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -1,8 +1,8 @@
-;;;; grob-property-description.scm -- part of generated backend documentation
+;;;; define-grob-properties.scm -- part of generated backend documentation

 ;;;;
 ;;;;  source file of the GNU LilyPond music typesetter
 ;;;; 
 ;;;;
 ;;;;  source file of the GNU LilyPond music typesetter
 ;;;; 

-;;;; (c) 1998--2007  Han-Wen Nienhuys <hanwen@xs4all.nl>
+;;;; (c) 1998--2008  Han-Wen Nienhuys <hanwen@xs4all.nl>

 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 
 (define (define-grob-property symbol type? description)
 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 
 (define (define-grob-property symbol type? description)


@@ -79,6 +79,14 @@ specifies which beams to make.  @code{0}@tie{}is the central beam,
 @code{1}@tie{}is the next beam toward the note, etc.  This
 information is used to determine how to connect the beaming patterns
 from stem to stem inside a beam.")
 @code{1}@tie{}is the next beam toward the note, etc.  This
 information is used to determine how to connect the beaming patterns
 from stem to stem inside a beam.")

+     (beamlet-default-length ,pair? "A pair of numbers. The first number
+specifies the default length of a beamlet that sticks out of the left hand
+side of this stem; the second number specifies the default length of the
+beamlet to the right. The actual length of a beamlet is determined by
+taking either the default length or the length specified by
+@code{beamlet-max-length-proportion}, whichever is smaller.")
+     (beamlet-max-length-proportion ,pair? "The maximum length of a 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.")


@@ -133,6 +141,8 @@ stick out of its bounds?")
 
      (c0-position ,integer? "An integer indicating the position of
 middle@tie{}C.")
 
      (c0-position ,integer? "An integer indicating the position of
 middle@tie{}C.")

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

      (clip-edges ,boolean? "Allow outward pointing beamlets at the
 edges of beams?")
      (collapse-height ,ly:dimension? "Minimum height of system start
      (clip-edges ,boolean? "Allow outward pointing beamlets at the
 edges of beams?")
      (collapse-height ,ly:dimension? "Minimum height of system start


@@ -168,6 +178,9 @@ other object.  Otherwise, it determines whether the object is placed
 be used: @code{#UP}=@code{1}, @code{#DOWN}=@code{-1},
 @code{#LEFT}=@code{-1}, @code{#RIGHT}=@code{1}, @code{#CENTER}=@code{0}.")
      (dot-count ,integer? "The number of dots.")
 be used: @code{#UP}=@code{1}, @code{#DOWN}=@code{-1},
 @code{#LEFT}=@code{-1}, @code{#RIGHT}=@code{1}, @code{#CENTER}=@code{0}.")
      (dot-count ,integer? "The number of dots.")

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

      (dot-placement-list ,list? "List 
 consisting of @code{(@var{description} @var{string-number} 
 @var{fret-number} @var{finger-number})} 
      (dot-placement-list ,list? "List 
 consisting of @code{(@var{description} @var{string-number} 
 @var{fret-number} @var{finger-number})} 


@@ -204,15 +217,21 @@ problem, we pad each item by this amount (by adding the @q{car} on the
 left side of the item and adding the @q{cdr} on the right side of the
 item).  In order to make a grob take up no horizontal space at all,
 set this to @code{(+inf.0 . -inf.0)}.")
 left side of the item and adding the @q{cdr} on the right side of the
 item).  In order to make a grob take up no horizontal space at all,
 set this to @code{(+inf.0 . -inf.0)}.")

+     (flag ,ly:stencil? "A function returning the full flag stencil for
+the @code{Stem}, which is passed to the function as the only argument.
+The default ly:stem::calc-stencil function uses the @code{flag-style}
+property to determine the correct glyph for the
+flag. By providing your own function, you can create arbitrary flags.")

      (flag-count ,number? "The number of tremolo beams.")
      (flag-count ,number? "The number of tremolo beams.")

-     (flag-style ,symbol? "A string determining what style of flag
-glyph is typeset on a @code{Stem}.  Valid options include @code{()}
-and @code{mensural}.  Additionally, @code{no-flag} switches off the
-flag.")
+     (flag-style ,symbol? "A symbol determining what style of flag
+glyph is typeset on a @code{Stem}.  Valid options include @code{'()} for
+standard flags, @code{'mensural} and @code{'no-flag}, which switches off 
+the flag.")

      (font-encoding ,symbol? "The font encoding is the broadest
      (font-encoding ,symbol? "The font encoding is the broadest

-category for selecting a font.  Options include: @code{fetaMusic},
-@code{fetaNumber}, @code{TeX-text}, @code{TeX-math},
-@code{fetaBraces}, @code{fetaDynamic}.")
+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).")

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


@@ -231,7 +250,6 @@ Fractional values are allowed.")
      (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}.")

-     (forced ,boolean? "Manually forced accidental.")

      (fraction ,number-pair? "Numerator and denominator of a time
 signature object.")
      (french-beaming ,boolean? "Use French beaming style for this
      (fraction ,number-pair? "Numerator and denominator of a time
 signature object.")
      (french-beaming ,boolean? "Use French beaming style for this


@@ -248,6 +266,9 @@ include the following:
 Choices include @code{curved}, @code{straight}, and
 @code{none}.  Default @code{curved}.
 @item
 Choices include @code{curved}, @code{straight}, and
 @code{none}.  Default @code{curved}.
 @item

+@code{capo-thickness} -- Thickness of capo indicator, in
+multiples of fret-space.  Default value 0.5.
+@item

 @code{dot-color} -- Color of dots.  Options include
 @code{black} and @code{white}.  Default @code{black}.
 @item
 @code{dot-color} -- Color of dots.  Options include
 @code{black} and @code{white}.  Default @code{black}.
 @item


@@ -327,18 +348,27 @@ The properties which can be included in harp-pedal-details
 include the following:
 @itemize @bullet
 @item
 include the following:
 @itemize @bullet
 @item

-@code{box-offset} -- Vertical shift of the center of flat / sharp pedal 
+@code{box-offset} -- Vertical shift of the center of flat / sharp pedal

 boxes above / below the horizontal line. Default value 0.8.
 @item
 @code{box-width} -- Width of each pedal box. Default value 0.4.
 @item
 @code{box-height} -- Height of each pedal box. Default value 1.0.
 @item
 boxes above / below the horizontal line. Default value 0.8.
 @item
 @code{box-width} -- Width of each pedal box. Default value 0.4.
 @item
 @code{box-height} -- Height of each pedal box. Default value 1.0.
 @item

-@code{space-before-divider} -- Space between boxes before the first divider 
+@code{space-before-divider} -- Space between boxes before the first divider

 (so that the diagram can be made symmetric). Default value 0.8.
 @item
 (so that the diagram can be made symmetric). Default value 0.8.
 @item

-@code{space-after-divider} -- Space between boxes after the first divider. 
+@code{space-after-divider} -- Space between boxes after the first divider.

 Default value 0.8.
 Default value 0.8.

+@item
+@code{circle-thickness} -- Thickness (in unit of the line-thickness) of the
+ellipse around circled pedals. Default value 0.5.
+@item
+@code{circle-x-padding} -- Padding in X direction of the ellipse around
+circled pedals. Default value 0.15.
+@item
+@code{circle-y-padding} -- Padding in Y direction of the ellipse around
+circled pedals. Default value 0.2.

 @end itemize")
 
      (head-direction ,ly:dir? "Are the note heads left or right in a
 @end itemize")
 
      (head-direction ,ly:dir? "Are the note heads left or right in a


@@ -480,6 +510,8 @@ In case of a potential collision, the grob with the smaller
 tightly as possible.")
      (padding ,ly:dimension? "Add this much extra space between
 objects that are next to each other.")
 tightly as possible.")
      (padding ,ly:dimension? "Add this much extra space between
 objects that are next to each other.")

+     (padding-pairs ,list? "An alist mapping @code{(@var{name} . @var{name})}
+to distances.")

      (page-break-penalty ,number? "Penalty for page break at this
 column.  This affects the choices of the page breaker; it avoids a
 page break at a column with a positive penalty and prefers a page break
      (page-break-penalty ,number? "Penalty for page break at this
 column.  This affects the choices of the page breaker; it avoids a
 page break at a column with a positive penalty and prefers a page break


@@ -508,7 +540,7 @@ dot.")
 number, the quicker the slur attains its @code{height-limit}.")
      (remove-empty ,boolean? "If set, remove group if it contains no
 interesting items.")
 number, the quicker the slur attains its @code{height-limit}.")
      (remove-empty ,boolean? "If set, remove group if it contains no
 interesting items.")

-     (remove-first ,boolean? "Remove the first staff of a orchestral
+     (remove-first ,boolean? "Remove the first staff of an orchestral

 score?")
      (restore-first ,boolean? "Print a natural before the
 accidental.")
 score?")
      (restore-first ,boolean? "Print a natural before the
 accidental.")


@@ -534,6 +566,10 @@ value @code{-1} means left aligned, @code{0}@tie{}centered, and
 values may also be specified.")
      (self-alignment-Y ,number? "Like @code{self-alignment-X} but for
 the Y@tie{}axis.")
 values may also be specified.")
      (self-alignment-Y ,number? "Like @code{self-alignment-X} but for
 the Y@tie{}axis.")

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

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


@@ -553,6 +589,14 @@ is placed vertically.")
 @code{direction-source} with this to get the direction of this
 object.")
      (size ,number? "Size of object, relative to standard size.")
 @code{direction-source} with this to get the direction of this
 object.")
      (size ,number? "Size of object, relative to standard size.")

+     (skyline-horizontal-padding ,number? "For determining the 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.")
+     (slash-negative-kern ,number? "The space to remove between
+slashes in percent repeat glyphs.  Larger values bring the two
+elements closer together.")

      (slope ,number? "The slope of this object.")
      (slur-padding ,number? "Extra distance between slur and script.")
      (space-alist ,list? "A table that specifies distances between
      (slope ,number? "The slope of this object.")
      (slur-padding ,number? "Extra distance between slur and script.")
      (space-alist ,list? "A table that specifies distances between


@@ -593,8 +637,8 @@ be?")
      (stencil ,ly:stencil? "The symbol to print.")
      (stencils ,list? "Multiple stencils, used as intermediate
 value.")
      (stencil ,ly:stencil? "The symbol to print.")
      (stencils ,list? "Multiple stencils, used as intermediate
 value.")

-     (strict-grace-spacing ,boolean? "If set, grace notes
-are not spaced separately, but put before musical columns.")
+     (strict-grace-spacing ,boolean? "If set, main notes are spaced
+normally, then grace notes are put left of the musical columns fot the main notes.")

      (strict-note-spacing ,boolean? "If set, unbroken columns
 with non-musical material (clefs, bar lines, etc.) are not spaced
 separately, but put before musical columns.")
      (strict-note-spacing ,boolean? "If set, unbroken columns
 with non-musical material (clefs, bar lines, etc.) are not spaced
 separately, but put before musical columns.")


@@ -715,6 +759,7 @@ the grob where this is set in.")
 in addition to notes and stems.")
 
      (figures ,ly:grob-array? "Figured bass objects for continuation line.")
 in addition to notes and stems.")
 
      (figures ,ly:grob-array? "Figured bass objects for continuation line.")

+     (forced ,boolean? "Manually forced accidental.")

 
      (glyph-name ,string? "The glyph name within the font.")
      (grace-spacing ,ly:grob? "A run of grace notes.")
 
      (glyph-name ,string? "The glyph name within the font.")
      (grace-spacing ,ly:grob? "A run of grace notes.")


@@ -737,9 +782,6 @@ columns.")
      (note-columns ,pair? "A list of @code{NoteColumn} grobs.")
      (note-head ,ly:grob? "A single note head.")
      (note-heads ,ly:grob-array? "A list of note head grobs.")
      (note-columns ,pair? "A list of @code{NoteColumn} grobs.")
      (note-head ,ly:grob? "A single note head.")
      (note-heads ,ly:grob-array? "A list of note head grobs.")

-
-     (padding-pairs ,list? "An alist mapping @code{(@var{name} . @var{name})}
-to distances.")

      (pedal-text ,ly:grob? "A pointer to the text of a mixed-style piano
 pedal.")
      (pure-Y-common ,ly:grob? "A cache of the
      (pedal-text ,ly:grob? "A pointer to the text of a mixed-style piano
 pedal.")
      (pure-Y-common ,ly:grob? "A cache of the


@@ -783,9 +825,6 @@ that should only show changes.")
 
      (cause ,scheme? "Any kind of causation objects (i.e., music, or perhaps
 translator) that was the cause for this grob.")
 
      (cause ,scheme? "Any kind of causation objects (i.e., music, or perhaps
 translator) that was the cause for this grob.")

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

      (delta-position ,number? "The vertical position difference.")
      (details ,list? "Alist of parameters for detailed grob behavior.
 
      (delta-position ,number? "The vertical position difference.")
      (details ,list? "Alist of parameters for detailed grob behavior.
 


@@ -828,11 +867,6 @@ acts as an index for looking up a @code{Stencil} object.")
 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.")
 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.")

-     (skyline-horizontal-padding ,number? "For determining the 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.")

      (stem-info ,pair? "A cache of stem parameters.")
 
      (use-breve-rest ,boolean? "Use breve rests for measures longer
      (stem-info ,pair? "A cache of stem parameters.")
 
      (use-breve-rest ,boolean? "Use breve rests for measures longer


@@ -847,7 +881,7 @@ than a whole rest.")
 
      ;; However, such a list would consist of a couple of dozens of
      ;; entries, since head prefixes may be combined in many ways.  If
 
      ;; However, such a list would consist of a couple of dozens of
      ;; entries, since head prefixes may be combined in many ways.  If

-     ;; the macros in `gregorian-init.ly' would directly set prefix-set,
+     ;; the macros in `gregorian.ly' would directly set prefix-set,

      ;; all the head prefixes could be junked; however, such macros
      ;; would be quite numerous, I guess.  --jr
 
      ;; all the head prefixes could be junked; however, such macros
      ;; would be quite numerous, I guess.  --jr