]> git.donarmstrong.com Git - lilypond.git/blob - scm/grob-property-description.scm
* scm/grob-property-description.scm: Remove regular-distance-to.
[lilypond.git] / scm / grob-property-description.scm
1 ;;;; grob-property-description.scm -- part of generated backend documentation
2 ;;;;
3 ;;;;  source file of the GNU LilyPond music typesetter
4 ;;;; 
5 ;;;; (c) 1998--2001  Han-Wen Nienhuys <hanwen@cs.uu.nl>
6 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
7
8
9
10 (define all-backend-properties '())
11
12 (define (grob-property-description symbol type? description)
13   (if (not (equal? (object-property symbol 'backend-doc) #f))
14       (begin
15         (ly-warn (string-append "Redefining " (symbol->string symbol) "\n"))
16         (exit 2)
17       ))
18   
19   (set-object-property! symbol 'backend-type? type?)
20   (set-object-property! symbol 'backend-doc description)
21   (set! all-backend-properties (cons symbol all-backend-properties))
22   )
23
24 ;; put this in an alist?
25
26 (grob-property-description 'X-extent-callback procedure? "procedure taking an grob and axis argument, returning a number-pair. The return value is the extent of the grob.
27
28 The size of a grob are determined through callbacks, settable with
29 grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
30 There can be only one extent-callback for each axis. No callback
31 (Scheme value @code{#f}) means: `empty in this direction'. If you fill
32 in a pair of numbers, that pair hard-codes the extent in that
33 coordinate.
34 ")
35 (grob-property-description 'X-offset-callbacks list? "list of functions, each taking an grob and axis argument. The function determine the position relative to this grob's parent. The last one in the list is called first.
36
37 Offsets of grobs are relative to a parent reference point. Most
38 positions are not known when an object is created, so these are
39 calculated as needed. This is done by adding a callback for a specific
40 direction.
41
42 Offset callbacks can be stacked, i.e.
43
44 @example
45         \property .... \override #'Y-offset-callbacks = #(list
46                 callback1 callback2 callback3)
47
48 @end example
49
50 The callbacks will be executed in the order @code{callback3 callback2
51 callback1}. This is used for quantized positioning: the staccato dot is
52 above or below a note head, and it must not be on a staff-line.  To
53 achieve this, the staccato dot has two callbacks: one that positions the
54 grob above or below the note head, and one that rounds the Y-position of
55 the grob to the nearest open space.
56
57
58 ")
59 (grob-property-description 'Y-extent-callback procedure? "see @code{X-extent-callback}.")
60 (grob-property-description 'Y-offset-callbacks list? "see @code{X-offset-callbacks}.")
61
62 (grob-property-description 'accidental-grobs list? "Alis with (NOTENAME . GROBLIST) entries")
63 (grob-property-description 'accidentals list? "List of alteration numbers.")
64 (grob-property-description 'add-stem boolean? "Add stem to porrectus?.")
65 (grob-property-description 'adjust-if-on-staffline boolean? "If this grob is on a staff line, adjust its appearance, so that it better fits into the staff.  E.g., if set true on stem grobs, flares of mensural flags will always be aligned with the staff lines, regardless if the associated note head is printed on a staff line or inbetween.")
66 (grob-property-description 'after-line-breaking-callback procedure? "Procedure taking a grob as argument.
67 This procedure is called (using dependency resolution) after line breaking. Return value is ignored.")
68 (grob-property-description 'align number? "the alignment of the text, 0 is horizontal, 1 is vertical.")
69 (grob-property-description 'align-dir dir? "Which side to align? -1: left side, 0: around center of width, 1: right side.")
70 (grob-property-description 'alignment-done boolean? "boolean to administrate whether we've done the alignment already (to ensure that the process is done only once).")
71 (grob-property-description 'all-elements grob-list? "list of all grobs in this line. Needed for protecting grobs from GC.")
72 (grob-property-description 'arch-angle number? "turning angle of the hook of a system brace" )
73 (grob-property-description 'arch-height number? "height of the hook of a system brace.")
74 (grob-property-description 'arch-thick number? "thickness of the hook of system brace.")
75 (grob-property-description 'arch-width number? "width of the hook of a system brace.")
76 (grob-property-description 'arpeggio ly-grob? "pointer to arpeggio object.") 
77 (grob-property-description 'arpeggio-direction dir? "If set, put an
78 arrow on the arpeggio squiggly line.")
79 (grob-property-description 'attachment pair? "cons of symbols
80 indicating how a slur should be attached at the ends. The format is
81 '(LEFT-TYPE . RIGHT-TYPE), where both TYPEs are symbols. The values of
82 these symbols may be alongside-stem, stem, head or loose-end.")
83 (grob-property-description 'attachment-offset pair? "cons of offsets,
84 '(LEFT-offset . RIGHT-offset).  This offset is added to the
85 attachments to prevent ugly slurs.  [fixme: we need more documentation here].
86 .")
87 (grob-property-description 'auto-properties boolean? "if true, as many properties of this grob as possible will be determined automatically from the musical context.")
88 (grob-property-description 'auto-knee-gap number? "If a gap is found between noteheads
89 where a  horizontal beam fits that is larger than this number,  make a kneed beam.")
90 (grob-property-description 'axes list? "list of axis numbers.
91 In the case of alignment grobs, this should contain only one number.")
92 (grob-property-description 'bar-size number? "size of a bar line.")
93 (grob-property-description 'bars grob-list? "list of barline pointers.")
94 (grob-property-description 'bar-size-procedure procedure? "Procedure that computes the size of a bar line.")
95 (grob-property-description 'base-shortest-duration moment?
96                            "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.")
97 (grob-property-description 'baseline-skip number? "Baseline skip to use for multiple lines of text.")
98 (grob-property-description 'bass list? " musical-pitch, optional.")
99 (grob-property-description 'beam ly-grob? "pointer to the beam, if applicable.")
100 (grob-property-description 'beam-thickness number? "thickness, measured in staffspace.")
101 (grob-property-description 'beam-width number? "width of the tremolo sign.")
102 (grob-property-description 'beamed-lengths list? "list of stem lengths given beam multiplicity .")
103 (grob-property-description 'beamed-minimum-free-lengths list? "list of normal minimum free stem lengths (chord to beams) given beam multiplicity.")
104 (grob-property-description 'beamed-extreme-minimum-free-lengths list? "list of extreme minimum free stem lengths (chord to beams) given beam multiplicity.")
105 (grob-property-description 'beamed-stem-shorten list? "shorten beamed stems in forced direction.")
106 (grob-property-description 'beaming pair?
107                            "Pair of number lists. Each number list
108 specifies which beams to make. 0 is the central beam, 1 is the next
109 beam toward the note etc. This information is used to determine how to
110 connect the beaming patterns from stem to stem inside a beam.")
111
112
113 (grob-property-description 'beautiful number? "number that dictates when a slur should be de-uglyfied.  It correlates with the enclosed area between noteheads and slurs.  A value of 0.1 yields only undisturbed slurs, a value of 5 will tolerate quite high blown slurs.")
114 (grob-property-description 'before-line-breaking-callback procedure? "Procedure taking grob as argument.
115 This procedure is called (using dependency resolution) before line breaking, but after generating discretionary items. Return value is ignored.")
116 (grob-property-description 'between-cols pair? "Where to attach a loose column to")
117 (grob-property-description 'between-system-string string? "string
118  to dump between two systems. Useful for forcing pagebreaks.")
119 (grob-property-description 'bounded-by-me grob-list? "list of spanners that have this
120 column as start/begin point. Only columns that have grobs or act as bounds are spaced.")
121 (grob-property-description 'bracket-thick number? "width of a system start bracket. .")
122 (grob-property-description 'break-align-symbol symbol? "the index in the spacing table (symbol) of the to be aligned item.")
123 (grob-property-description 'break-glyph-function procedure? "function taking glyph and break-direction, returning the glyph at a line break.")
124 (grob-property-description 'breakable boolean? "boolean indicating if this is a breakable item (clef, barline, key sig, etc.).")
125 (grob-property-description 'c0-position integer? "integer indicating the position of central C.")
126 (grob-property-description 'cautionary-style symbol? "style  of cautionary accidentals. Choices are 'smaller (one size smaller) or 'parentheses.")
127 (grob-property-description 'cautionary boolean? "is this a cautionary accidentals.?")
128
129 (grob-property-description 'center-element ly-grob? "grob which will
130 be at the center of the group after aligning (when using
131 Align_interface::center_on_element). .")
132 (grob-property-description 'concaveness-gap number? "A beam is
133 considered to be concave if the distance of an inner notehead to the
134 line between two outer noteheads is bigger than this gap.")
135 (grob-property-description 'concaveness-threshold number? "A beam is
136 considered to be concave is concaveness is bigger than this threshold.
137 Concaveness is calculated as the sum of the vertical distances of
138 inner noteheads that fall outside the interval of the two outer
139 noteheads, to the vertically nearest outer notehead, divided by the
140 square of the inner notes involved.")
141 (grob-property-description 'collapse-height number? "Minimum height of system start delimiter.  If equal or smaller, the bracket is removed.")
142
143 (grob-property-description 'columns grob-list? "list of grobs, typically containing paper-columns.")
144 (grob-property-description 'conditional-elements grob-list? "Internal use only")
145 (grob-property-description 'control-points list? "List of 4 offsets (number-pairs) that form control points for the  tie/slur shape.")
146 (grob-property-description 'damping integer? "amount of beam slope damping should beam slope be damped? 0: no, 1: yes, 100000: horizontal beams .")
147 (grob-property-description 'dash-length number? "the length of a dash.")
148 (grob-property-description 'dash-period number? "the length of one dash + white space.")
149 (grob-property-description 'dashed number? "[FIXME: use dash-period/dash length; see text-spanner] number representing the length of the dashes.")
150 (grob-property-description 'de-uglify-parameters list? "list of 3 real constants. They define the valid areas for the middle control points. Used in de_uglyfy. They are a bit empirical.")
151
152 (grob-property-description 'neutral-direction dir? "Where to go if we're on the neutral position of the staff (by default, the middle of the staff; see also grob-property neutral-position).  [Ross] has the following to say about this: Some engravers consider the middle line neutral, and take the option of using either up- or down-stems for notes that fall on it. However, more up-to-date engraving no longer permits an option; now a down-stem is always appropriate.")
153 (grob-property-description 'neutral-position number? "Position (in half staff spaces) where to flip the direction of stems: by default, custodes above this position get their stems downwards; custodes below this position get their stems upwards.  A value of 0 designates the center of the staff.  Use property neutral-direction to control the behaviour of stems on the neutral position itself.  (Note: currently, neutral-position is supported only for custodes; for stems of note heads, neutral-position is currently fixed to 0, i.e. the middle of the staff.)")
154 (grob-property-description 'dependencies grob-list? "list of score-grob pointers that indicate who to compute first for certain global passes.")
155 (grob-property-description 'details list? "alist of parameters for detailed grob behavior.")
156 (grob-property-description 'dir-function procedure? "function of type (count total)->direction.  Default value: beam-dir-majority, also available: beam-dir-mean, beam-dir-median.
157
158 The ways to calculate the direction of a beam work as follows:
159 @table @code
160 @item majority
161 number count of up or down notes
162 @item mean
163 mean center distance of all notes
164 @item median
165 mean centre distance weighted per note
166 @end table
167
168 ")
169 (grob-property-description 'direction dir? "up or down, left or right?.")
170 (grob-property-description 'direction-source ly-grob? "in case side-relative-direction is set, which grob  to get the direction from .")
171 (grob-property-description 'dot ly-grob? "reference to Dots object.")
172 (grob-property-description 'dot-count integer? "number of dots.")
173 (grob-property-description 'duration-log integer? "2-log of the notehead duration, i.e. 0=whole note, 1 = half note, etc.")
174 (grob-property-description 'edge-height pair? "a cons that specifies the heights of the vertical edges '(LEFT-height . RIGHT-height).")
175 (grob-property-description 'edge-widen pair? "a cons that specifies the widths of the slanted edges '(LEFT-width . RIGHT-width).")
176 (grob-property-description 'edge-text pair? "a cons that specifies the texts to be set at the edges '(LEFT-text . RIGHT-text).")
177 (grob-property-description 'elements grob-list? "list of grobs, type depending on the Grob where this is set in.")
178 (grob-property-description 'expand-limit integer? "maximum number of measures expanded in church rests.")
179 (grob-property-description 'extra-X-extent number-pair? "enlarge in X dimension by this much, measured in staff space.")
180 (grob-property-description 'extra-Y-extent number-pair? "see @code{extra-Y-extent}.")
181 (grob-property-description 'X-extent number-pair? "Store extent. internal use only. ")
182 (grob-property-description 'Y-extent number-pair? "Store extent. internal use only. ")
183 (grob-property-description 'extra-offset number-pair? "pair of reals
184 (a cons) forcing an extra offset before outputting.
185 @code{extra-offset} is added just before `printing' the grob, so the
186 typesetting engine is completely oblivious to it.
187 ")
188 (grob-property-description 'extremity-offset-alist list? "an alist (attachment stem-dir*dir slur-dir*dir) -> offset.  The offset adds to the centre of the notehead, or stem.")
189
190 (grob-property-description 'extremity-rules list? "an alist (procedure
191 slur dir) -> attachment to determine the attachment (see above).  If
192 procedure returns #t, attachment is used.  Otherwise, the next
193 procedure is tried.")
194 (grob-property-description 'flag-style string? "set to \"grace\" to turn stroke through stem on.")
195 (grob-property-description 'flag-width-function procedure? "Procedure that computes the width of a half-beam (a non-connecting beam.).")
196 (grob-property-description 'flexa-width number? "width of a flexa shape in a ligature grob.")
197 (grob-property-description 'font-family symbol? "partial font
198 definition: music roman braces dynamic math ...")
199 (grob-property-description 'font-name string? "file name for the font to load.
200 Overrides all other font-X qualifiers.")
201 (grob-property-description 'font-design-size number? "partial font definition: exact font size in points FIXME: should override font-relative-size.")
202 (grob-property-description 'font-magnification number? "Magnification
203   of the font. If undefined, the default is @code{1.0}.")
204 (grob-property-description 'font-relative-size number? "partial font definition: the relative size compared the `normal' size.
205  0 is style-sheet's normal size, -1 is smaller, +1 is bigger, -1 is smaller.")
206 (grob-property-description 'font-series symbol? "partial font definition: medium, bold.")
207 (grob-property-description 'font-shape symbol? "partial font definition: upright or italic.")
208
209 (grob-property-description 'font-style symbol? "a precooked set of font
210 definitions, eg. finger volta timesig mark script large Large
211 dynamic.")
212
213 (grob-property-description 'force-hshift number? "amount of
214 collision_note_width that overides automatic collision settings. This
215 is used by @ref{note-collision-interface}.")
216
217 (grob-property-description 'fraction number-pair? "fraction of a time signature.")
218 (grob-property-description 'french-beaming boolean? "Use French
219 beaming style: stems stop at innermost beams.")
220 (grob-property-description 'full-size-change boolean? "if set, don't make a change clef smaller.")
221
222 (grob-property-description 'glyph string? "a string determining what (style) of  glyph is typeset. Valid choices depend on the function that is reading this property. .")
223 (grob-property-description 'glyph-name string? "a name of character within font.")
224
225 (grob-property-description 'gap number? "Size of a gap in a variable symbol.")
226
227 (grob-property-description 'grow-direction dir? "crescendo or decrescendo?.")
228 (grob-property-description 'hair-thickness number? "thickness, measured in stafflinethickness.")
229 (grob-property-description 'heads pair? "Pair of grob pointers, pointing to the two heads of the  tie.")
230 (grob-property-description 'height number? "in staffspace.")
231 (grob-property-description 'height-limit number? "Maximum slur height,
232   long slurs approach this height.
233
234   For small width w, the height should be proportional to w, for w ->
235   infinity, the height should rise to limit h_infinity asymptotically.
236
237   Hence we take F (x) such that
238 @quotation
239 @example  
240   F (0) = 0 , F' (0) = 1, and F (infinity) = 1
241 @end example
242 @end quotation
243   where
244 @quotation
245 @example  
246   h = height-limit * F (x * ratio / height-limit)
247 @end example
248 @end quotation
249   Currently, for F we use
250 @quotation
251 @example  
252   F (x) = 2/pi * atan (pi * x/2)
253 @end example
254 @end quotation
255 ")
256 (grob-property-description 'horizontal-shift integer? "integer that identifies ranking of note-column for horizontal shifting. This is used by @ref{note-collision-interface}.")
257 (grob-property-description 'ideal-distances list? "(OBJ . (DIST . STRENGTH)) pairs.")
258 (grob-property-description 'interfaces list? "list of symbols indicating the interfaces supported by this object. Is initialized from the @code{meta} field.")
259 (grob-property-description 'inversion list? " musical-pitch, optional.")
260 (grob-property-description 'items-worth-living grob-list? "list of interesting items. If empty in a particular system, clear that system.")
261 (grob-property-description 'join-heads boolean? "Whether to join the noteheads of an ambitus grob with a vertical line.")
262 (grob-property-description 'kern number? "amount of extra white space to add.
263
264 For text,  this is `relative'(?) to the current alignment.
265
266 For barline, space after a thick line.")
267 (grob-property-description 'knee boolean? "Is this beam a knee?")
268 (grob-property-description 'knee-spacing-correction number? "optical correction amount for knees. 0: no correction; 1: full correction.")
269 (grob-property-description 'layer number? "The output layer [0..2].  The default is 1.")
270
271 (grob-property-description 'left-position number? "position of left part of spanner.")
272 (grob-property-description 'right-position number? "position of right part of spanner.")
273 (grob-property-description 'left-padding number? "space left of accs.")
274 (grob-property-description 'right-head ly-grob? "")
275 (grob-property-description 'left-head ly-grob? "")
276
277 (grob-property-description 'left-widen boolean? "Whether the left edge of a piano pedal bracket should be widened by the first element of edge-widen.")
278
279 (grob-property-description 'length number? "Stem length for unbeamed stems, only for user override.")
280 (grob-property-description 'lengths list? "Stem length given
281 multiplicity of flag.  The Nth element of the list gives the stem
282 length of a note with N flags.
283 ")
284 (grob-property-description 'line-count integer? "Number of staff
285 lines.  If you want to override this for staffs individually, you must
286 use @code{\outputproperty}. @code{\property .. \override} will not
287 work: @code{\override} is processed after the StaffSymbol is created,
288 and will have no effect.
289 ")
290 (grob-property-description 'lookup symbol? "lookup method: 'value for plain text, 'name for character-name.")
291 (grob-property-description 'magnify number? "the magnification factor.  FIXME: doesn't work for feta fonts.")
292 (grob-property-description 'maximum-length number? "don't make Grob longer than this")
293 (grob-property-description 'maximum-rest-count integer? "kill off rests so we don't more than this number left.")
294 (grob-property-description 'measure-length moment? "Length of a
295 measure. Used in some spacing situations.")
296 (grob-property-description 'measure-count integer? "number of measures for a multimeasure rest.")
297
298 (grob-property-description 'merge-differently-headed boolean? "Merge
299 noteheads in collisions, even if they have different note heads. The
300 smaller of the two heads will be rendered invisible. This used
301 polyphonic guitar notation. The value of this setting is used by
302 @ref{note-collision-interface} .")
303
304 (grob-property-description 'merge-differently-dotted boolean? " Merge
305 noteheads in collisions, even if they have a different number of
306 dots. This normal notation for some types of polyphonic music. The
307 value of this setting is used by @ref{note-collision-interface} .")
308
309 (grob-property-description 'meta list? "Alist of meta information of this grob.
310
311 The alist contains the following entries: name, interfaces.
312
313
314
315 ")
316 (grob-property-description 'minimum-distance number? "minimum distance between notes and rests.")
317 (grob-property-description 'minimum-distances list? "list of rods (ie. (OBJ . DIST) pairs).")
318
319 (grob-property-description 'minimum-X-extent number-pair? "minimum size in X dimension, measured in staff space.")
320 (grob-property-description 'minimum-Y-extent number-pair? "see @code{minimum-Y-extent}.")
321 (grob-property-description 'minimum-length number? "try to make the
322 Grob at least this long.
323
324 Also works as a scaling parameter for the length of hyphen. .")
325
326 ;; FIXME.
327 (grob-property-description 'minimum-space number? "minimum distance that the victim should move (after padding).
328
329 FIXME: also pair? (cons LEFT RIGHT)
330
331 ")
332 (grob-property-description 'molecule-callback procedure? "Function
333 taking grob as argument, returning a smobbed Molecule.
334
335 All visible, i.e. non-transparent, grobs have a callback to create a
336 Molecule. The callback should be a Scheme function taking one argument
337 (the grob) and returning a Molecule.  Most molecule callbacks are
338 written in C++, but you can also write them in Scheme. An example is
339 provided in @code{input/regression/molecule-hacking.ly}.
340 ")
341
342 (grob-property-description 'molecule molecule? "Cached output of the molecule-callback.")
343
344 (grob-property-description 'new-accidentals list? "list of (pitch, accidental) pairs.")
345 (grob-property-description 'no-spacing-rods boolean? "read from grobs: boolean that makes Separation_item ignore this item (MOVE ME TO ITEM).")
346 (grob-property-description 'no-stem-extend boolean? "should stem not be extended to middle staff line?.")
347 (grob-property-description 'non-default boolean? "not set because of existence of a bar?.")
348 (grob-property-description 'note-head-style string? "name of the font character to be used as note heads in the ambitus grob.")
349 (grob-property-description 'note-heads grob-list? "List of note head grobs")
350 (grob-property-description 'number-threshold number? "only put numbers bigger than this threshold over multi measure rest.")
351 (grob-property-description 'old-accidentals list? "list of (pitch, accidental) pairs.")
352 (grob-property-description 'outer boolean? "whether a text spanner should extend to the outer edge of the spanned notes")
353 (grob-property-description 'padding number? "add this much extra space between objects that are next to each other.")
354 (grob-property-description 'pedal-type symbol? "Style of piano pedal: text, bracket or mixed.")
355 (grob-property-description 'pedal-text ly-grob? "Pointer to the text of a mixed-style piano pedal.")
356 (grob-property-description 'penalty number? "Penalty for breaking at
357 this column. 10000 or more means forbid linebreak, -10000 or less
358 means force linebreak.  Other values influence linebreaking decisions
359 as a real penalty.")
360
361 (grob-property-description 'pitch-max pitch? "FIXME, JUNKME")
362 (grob-property-description 'pitch-min pitch? "FIXME, JUNKME")
363
364
365 (grob-property-description 'pitches list? "list of musical-pitch.")
366 (grob-property-description 'positions pair? "cons of staff positions (LEFT . RIGHT")
367 (grob-property-description 'raise number? "height for text to be raised (a negative value lowers the text.")
368 (grob-property-description 'ratio number? "Slur parameter.  See height-limit.")
369 (grob-property-description 'right-padding number? "space right of accs.")
370 (grob-property-description 'right-trim-amount number? "shortening of the lyric extender on the right.")
371 (grob-property-description 'right-widen boolean? "Whether the right edge of a piano pedal bracket should be widened by the second element of edge-widen")
372 (grob-property-description 'script-priority number? "A sorting key that determines in what order a script is within a stack of scripts.")
373 (grob-property-description 'self-alignment-X number-or-grob? "real number: -1 =
374 left aligned, 0 = center, 1 right-aligned in X direction.
375
376  Set to an grob pointer, if you want that grob to be the center.
377 In this case, the center grob should have this object as a
378 reference point.
379
380 TODO: revise typing.")
381 (grob-property-description 'self-alignment-Y number? "like self-alignment-X but for Y axis.")
382 (grob-property-description 'shorten number? "the amount of space that a stem should be shortened (DOCME!)")
383 (grob-property-description 'shorten-pair number-pair? "the length on each side to shorten a text-spanner, for example a pedal bracket")
384 (grob-property-description 'common-shortest-duration moment?
385                            "The most common shortest note length.
386 This is used in spacing. Making this larger will make the score tighter.")
387 (grob-property-description 'shortest-duration-space number? "Start
388 with this much space for the shortest duration. This is explessed in @code{spacing-increment} as unit. See also
389 @ref{spacing-spanner-interface}.")
390 (grob-property-description 'shortest-playing-duration moment? "duration of the shortest playing in that column.")
391 (grob-property-description 'shortest-starter-duration moment? "duration of the shortest notes that starts exactly in this column.")
392 (grob-property-description 'side-relative-direction dir? "if set: get the direction from a different object, and multiply by this.")
393 (grob-property-description 'side-support-elements grob-list? "the support, a list of grobs.")
394 (grob-property-description 'slope number? "some kind of slope")
395 (grob-property-description 'slope-limit number? "set slope to zero if slope is running away steeper than this.")
396 (grob-property-description 'solid boolean? "should porrectus be solidly filled?.")
397
398 (grob-property-description 'space-alist list? "Alist of break align
399 spacing tuples: format = (SYMBOL . (TYPE . DISTANCE)), where TYPE can be
400 minimum-space or extra-space.")
401 (grob-property-description 'space-function procedure? "return interbeam space given Beam grob and multiplicity.")
402 (grob-property-description 'spacing-increment number? "Add this much space for a doubled duration. Typically, the width of a note head. See also @ref{spacing-spanner-interface}.")
403
404 (grob-property-description 'spacing-wishes grob-list? "List of note spacing or staff spacing objects.")
405 (grob-property-description 'spacing-procedure procedure? "procedure
406 taking grob as argument. This is called after
407 before-line-breaking-callback, but before the actual line breaking
408 itself.  Return value is ignored.")
409 (grob-property-description 'stacking-dir dir? "stack contents of grobs in which direction ?.")
410 (grob-property-description 'staff-space number? "Amount of line leading relative to global staffspace.")
411 (grob-property-description 'staff-position number? "vertical position in staff spaces, counted from the middle line.")
412
413 (grob-property-description 'staffline-clearance number? "don't get closer than this to stafflines.")
414 (grob-property-description 'stem ly-grob? "pointer to Stem object.")
415 (grob-property-description 'stem-attachment-function procedure? "Where
416 does the stem attach to the notehead? Function takes a symbol argument
417 being the style. It returns a (X . Y) pair, specifying location in
418 terms of note head bounding box.")
419 (grob-property-description 'stem-end-position number? "Where does the stem end (the end is opposite to the support-head.")
420
421 (grob-property-description 'stem-shorten list? "shorten stems in forced directions given flag multiplicity:
422 the Nth element of the list gives the amount stem shortening of a note with N flags.
423 ")
424 (grob-property-description 'stem-spacing-correction number? "optical correction amount.  [TODO: doco] ")
425 (grob-property-description 'stems grob-list? "list of stem objects, corresponding to the notes that the arpeggio has to be before.")
426 (grob-property-description 'style symbol? "a string determining what style of  glyph is typeset. Valid choices depend on the function that is reading this property. .")
427 (grob-property-description 'support-head ly-grob? "the note head at
428 one end of the stem.")
429 (grob-property-description 'text markup? "
430 Scheme markup text.  It is defined as follows:
431
432 @example
433 text: string | (head? text+)
434 head: markup | (markup+)
435 markup-item: property | abbrev
436 property: (@var{key} . @var{value})
437 abbrev: @code{columns lines roman music bold italic named super sub overstrike text}
438         @code{finger volta timesig mmrest mark script large Large dynamic}
439 @end example
440
441
442 The following abbreviations are currently defined:
443 @table @samp
444 @item columns
445  horizontal mode: set all text on one line (default)
446 @item lines
447  vertical mode: set every text on new line
448 @item roman
449  select roman font
450 @item music
451  select feta font, and lookup by character name
452 @item bold
453  select bold series
454 @item italic
455  select italic shape
456 @item named
457  lookup by character name
458 @item text
459  plain text lookup (by character value)
460 @item super
461  superscript
462 @item sub
463  subscript
464 @item overstrike
465  the next text or character overstrikes this one
466 @item finger
467  select fingering number fontstyle
468 @item volta
469  select volta number fontstyle
470 @item timesig
471  select time signature number fontstyle
472 @item mmrest
473  select multi measure rest number fontstyle
474 @item mark
475  select mark number fontstyle
476 @item script
477  select scriptsize roman fontstyle
478 @item large
479  select large roman fontstyle
480 @item Large
481  select Large roman fontstyle
482 @item dynamic
483  select dynamics fontstyle
484 @end table
485 .")
486 (grob-property-description 'text-start boolean? "Indicator for whether a piano pedal bracket has leading text, such as Ped.")
487 (grob-property-description 'thick-thickness number? "thickness, measured in stafflinethickness.")
488 (grob-property-description 'thickness number? "thickness, measured in stafflinethickness.")
489 (grob-property-description 'thin-kern number? "space after a hair-line.")
490 (grob-property-description 'forced-distance number? "forced distance for an alignment.")
491
492 (grob-property-description 'threshold number-pair? "(cons MIN MAX), where MIN and MAX are dimensions in staffspace.")
493 (grob-property-description 'transparent boolean? "This is almost the
494 same as setting molecule-callback to #f, but this retains the
495 dimensions of this grob, which means that you can erase grobs
496 individually. .")
497 (grob-property-description 'bracket-visibility boolean-or-symbol? "
498 This controls the visibility of the tuplet bracket.
499 Setting it to false will prevent printing of the
500 bracket. Setting the property to #'if-no-beam will make it
501 print only if there is no beam associated with this tuplet bracket.")
502 (grob-property-description 'number-visibility boolean-or-symbol? "
503 Like @code{bracket-visibility}, but for the number.")
504 (grob-property-description 'tie ly-grob? "") 
505 (grob-property-description 'type symbol? " 
506
507 one of: line, dashed-line, trill or dotted-line.
508
509 [FIXME: type is too generic for this doc, move doco to intefrace] 
510 ")
511
512 (grob-property-description 'break-visibility procedure? "a function that takes the break direction and returns a  cons of booleans containing (TRANSPARENT . EMPTY).
513
514
515 Some items need special treatment for line breaking. For example, a
516 clef is normally only printed at the start of a line (i.e. after a line
517 break).  To model this, `breakable' items (clef, key signature, bar lines,
518 etc.) are copied twice. Then we have three versions of each breakable
519 item: one version if there is no line break, one version that is printed
520 before the line break (at the end of a system), one version that is
521 printed after the line break.
522
523 Whether these versions are visible and take up space, is determined by
524 the outcome of the @code{break-visibility}. This grob property is a
525 function taking a direction (-1, 0 or 1) as argument. It returns a cons
526 of booleans, signifying whether this grob should be transparent and have
527 no extent.
528
529 ")
530 (grob-property-description 'when moment? "when does this column happen?.")
531 (grob-property-description 'word-space number? "elongate left by this much (FIXME: cumbersome semantics).")
532 (grob-property-description 'alignment number? "alignment of lyrics on notehead, -1 is LEFT, 0 is CENTRE, 1 is RIGHT .")
533 (grob-property-description 'ignore-length-mismatch boolean? "if #t, stanzas with shorter lyrics can be moved away from their respective note-head by the lyric alignment code.")
534 (grob-property-description 'begin-alignment number? "proportion of lyric length from beginning to align with note-head for left-aligned lyrics.")
535 (grob-property-description 'end-alignment number? "proportion of lyric length from end to align with note-head for right-aligned lyrics.")
536 (grob-property-description 'width number? "width of a grob measured in staff space.")
537 (grob-property-description 'width-correct number? "width correction for (de)cresc. text spanners.")
538 (grob-property-description 'x-gap number? "horizontal gap between notehead and tie.")
539 (grob-property-description 'y-free number? "minimal vertical gap between slur and noteheads or stems.")
540 (grob-property-description 'y-offset number? "extra vertical offset for ties away from the center line.")
541
542
543 ;;; INTERNAL
544
545 (grob-property-description 'left-neighbors grob-list? " List of
546 spacing-wish grobs that are close to the current column.
547
548 The closest spacing-wishes determine the actual distances between the
549 columns.
550 ")
551 (grob-property-description 'right-neighbors grob-list? "see left-neighbors")
552 (grob-property-description 'left-items grob-list? "")
553 (grob-property-description 'right-items grob-list? "")
554
555 (grob-property-description 'cause scheme? "Any kind of causation objects (i.e. music, or perhaps translator) that was the cause for this grob.  ")
556 (grob-property-description 'font font-metric? "Cached font metric object")
557 (grob-property-description 'break-alignment-done boolean? "mark flag to signal we've done alignment already.")
558 (grob-property-description 'staff-symbol ly-grob? "the staff symbol grob that we're in.")
559 (grob-property-description 'collision-done boolean? "")
560 (grob-property-description 'rest ly-grob? "the staff symbol grob that we're in.")
561 (grob-property-description 'rest-collision ly-grob? "rest collision that a rest is in.")
562
563 (grob-property-description 'staff-support boolean? " JUNKME.")
564 (grob-property-description 'script-molecule pair? "index code for script.")
565
566 (grob-property-description 'accidental-grob ly-grob? "Accidental for this note.")
567
568 (grob-property-description 'causes list? "list of cause objects; these can be music objects or grobs.")
569 (grob-property-description 'flag-count number? "")
570 (grob-property-description 'chord-tremolo boolean? "if set, this beam is a tremolo. TODO: use interface for this!")
571 (grob-property-description 'chord pair? "?")
572 (grob-property-description 'begin-of-line-visible boolean? "?")
573
574 (grob-property-description 'quant-score number? "Beam quanting score
575 -- can be stored for debugging")
576 (grob-property-description 'least-squares-dy number? 
577  "ideal beam slope, without damping.")
578 (grob-property-description 'ligature-primitive-callback number? "DOCME")
579 (grob-property-description 'stem-info pair? "caching of stem parameters")
580 (grob-property-description 'note-columns pair? "list of NoteColumn grobs.")
581
582 (grob-property-description 'if-text-padding number? "padding in case texts are there.")
583 (grob-property-description 'grace-space-factor number? "space grace at this fraction of the increment.")
584 (grob-property-description 'position-callbacks list? "list of
585 functions set spanner positions.")
586 (grob-property-description 'join-left number? "DOCME")
587 (grob-property-description 'delta-pitch number? "DOCME")
588 (grob-property-description 'head-width number? "DOCME")
589 (grob-property-description 'primitive number? "DOCME")
590 (grob-property-description 'chord-name-function procedure? "DOCME")
591 (grob-property-description 'minimum-beam-collision-distance number?
592 "Minimum distance to beam for a rest collision.")
593
594 (grob-property-description 'avoid-note-head boolean? "if set, the stem of a chord does not pass through all note head, but start at the last note head. Used by tablature.")
595 (grob-property-description 'up-to-staff boolean? "if set, stems' lengths are set so as stems end out of the staff. Used by tablature.")