]> git.donarmstrong.com Git - lilypond.git/blob - scm/translator-property-description.scm
* lily/rest-collision.cc (force_shift_callback): rewrite using
[lilypond.git] / scm / translator-property-description.scm
1
2 (define-public all-translation-properties '())
3
4 (define (translator-property-description symbol type? description)
5  (if (not (equal? #f (object-property symbol 'translation-doc)))
6       (begin
7         (ly:warn (string-append "Redefining " (symbol->string symbol) "\n"))
8         (exit 2)
9       ))
10   
11   (set-object-property! symbol 'translation-type? type?)
12   (set-object-property! symbol 'translation-doc description)
13   (set! all-translation-properties (cons symbol all-translation-properties))
14   )
15
16
17
18 (translator-property-description 'extraVerticalExtent
19                                  number-pair? "extra vertical extent, same format as  MinimumVerticalExtent")
20 (translator-property-description 'minimumVerticalExtent number-pair?
21                                  "minimum vertical extent, same format as VerticalExtent")
22 (translator-property-description 'verticalExtent number-pair?
23                                  "hard coded vertical extent.
24 The format is a pair of dimensions, for example, this sets the sizes
25 of a staff to 10 (5+5) staffspaces high.
26
27 @example
28 property Staff.verticalExtent = #(-5.0 . 5.0)
29 @end example
30
31 VerticalExtent, MinimumVerticalExtent and ExtraVerticalExtent are
32 predefined in all relevant contexts to @code{#f}, so they will not
33 inherit values.
34
35 Note that these VerticalExtents can only operate on vertical groups,
36 and therefore only work in contexts which contain an
37 @code{Axis_group_engraver}.
38 ")
39
40 (translator-property-description
41  'acknowledgeHashTable vector?
42  "Internal variable: store interface to engraver smob table for current context. Don't mess with this."
43  )
44
45 (translator-property-description 'acceptHashTable vector? "Internal
46 variable: store table with MusicName to Engraver entries.")
47 (translator-property-description 'aDueText string? "text for begin of a due")
48 (translator-property-description 'associatedVoice string? "Name of the Voice that has the melody for this LyricsVoice.")
49 (translator-property-description 'autoBeamSettings list? "
50 Specifies when automatically generated beams should begin and end.  The elements have the format:
51
52 @example
53
54    function shortest-duration-in-beam time-signature
55
56 where
57
58     function = begin or end
59     shortest-duration-in-beam = numerator denominator; eg: 1 16
60     time-signature = numerator denominator, eg: 4 4
61
62 unspecified or wildcard entries for duration or time-signature
63 are given by * *
64
65 The user can override beam begin or end time by pushing a wildcard entries
66 '(begin * * * *) or '(end * * * *) resp., eg:
67
68     property Voice.autoBeamSettings push #'(end * * * *) = #(ly:make-moment 1 4)
69
70 The head of the list:
71     '(
72 ((end * * 3 2) . ,(ly:make-moment 1 2))
73 ((end 1 16 3 2) . ,(ly:make-moment 1 4))
74 ((end 1 32 3 2) . ,(ly:make-moment 1 8))
75      ...
76     )
77
78 @end example")
79
80 (translator-property-description 'autoAccidentals list? "List of
81 different ways to typeset an accidental. All algorithms in the list
82 are tried, and the one returning the most accidentals is used.
83 Each entry is either a symbol containg a context name or a name-value
84 pair containing an algorithm-description.
85 The list must begin with a symbol (context name).
86 The symbols denote in which context THE FOLLOWING algorithms (until next symbol) 
87 will be interpreted. All notes in the interpretation context will share accidentals.
88 The contexts must be stated in order, innermost first.
89 The algorithms are:
90 @table @samp
91 @item same-octave:
92 This is the default algorithm. Accidentals are typeset if the note changes
93 the accidental of that note in that octave. Accidentals lasts to the end of the measure 
94 and then as many measures as specified in the value. I.e. 1 means to the end
95 of next measure, -1 means to the end of previous measure (that is: no duration at all), etc. #t means forever.
96 @item any-octave:
97 Accidentals are typeset if the note is different from 
98 the previous note on the same pitch in any octave. The value has same meaning as in
99 same-octave.
100 @end table
101 ")
102
103 (translator-property-description 'autoCautionaries list? "List similar to
104 autoAccidentals, but it controls cautionary accidentals rather than
105 normal ones. Both lists are tried, and the one giving the most accidentals
106 wins. In case of draw, a normal accidental is typeset.
107 ")
108
109 (translator-property-description 'automaticPhrasing boolean? " If set,
110 the @ref{Lyric_phrasing_engraver} will match note heads of context
111 called Voice X to syllables from LyricsVoice called
112 X-<something>. This feature is turned on by default. See the example
113 file @file{lyrics-multi-stanza.ly}.
114 ")
115
116 (translator-property-description 'automaticMelismata boolean? " If
117 set, \\addlyrics will assume that beams, slurs and ties signal
118 melismata, and align lyrics accordingly.
119 ")
120
121 (translator-property-description 'barAlways boolean? " If set to true a bar line is drawn after each note.
122 ")
123 (translator-property-description 'barCheckSynchronize boolean? "If
124 true then reset measurePosition when finding a barcheck. Turn off when
125 using barchecks in polyphonic music.")
126 (translator-property-description 'barNonAuto boolean? " If set to true then bar lines will not be printed
127     automatically; they must be explicitly created with @code{bar}
128     keywords.  Unlike with the @code{cadenza} keyword, measures are
129     still counted.  Bar generation will resume according to that
130     count if this property is set to zero.
131 ")
132 (translator-property-description 'barNumberVisibility procedure? "Procedure that takes an int and returns whether the corresponding bar number should be printed")
133 (translator-property-description 'beamMelismaBusy boolean? "Signal if a beam is set when automaticMelismata is set")
134 (translator-property-description 'beatLength ly:moment? "The length of one beat in this time signature.")
135 (translator-property-description 'breakAlignOrder list? "Defines the order in which
136 prefatory matter (clefs, key signatures) appears, eg. this puts the
137 key signatures after the bar lines:
138
139 @example
140         \\property Score.breakAlignOrder = #'(
141           span-bar
142           breathing-sign
143           clef
144           staff-bar
145           key
146           time-signature
147         )
148 @end example
149 ")
150 (translator-property-description 'busyGrobs list? "
151 a queue of (END-MOMENT . GROB) conses. This is for internal (C++) use only.
152 Use at your own risk.  This property contains the grobs for which  END-MOMENT >= NOW.
153 ")
154
155 (translator-property-description 'centralCPosition number? "Place of
156 the central C, measured in half staffspaces.  Usually determined by
157 looking at clefPosition and clefGlyph.")
158
159 (translator-property-description
160  'changeMoment moment-pair?
161  "duration that voices are examined for differences, when
162 part-combining.  Usually unset or zero when combining threads into one
163 voice, and 1 (or the duration of one measure) when combining voices
164 into one staff.")
165
166 (translator-property-description 'chordChanges boolean? "Only show changes in chords scheme?")
167 (translator-property-description 'clefGlyph string? "Name of the symbol within the music font")
168 (translator-property-description 'clefOctavation integer? "Add
169 this much extra octavation. Values of 7 and -7 are common.")
170
171 (translator-property-description 'clefPosition number? "Where should
172 the center of the clef symbol go?  On systems with an odd number of
173 stafflines, the value 0 puts the clef on the middle staffline; a
174 positive value shifts it up, a negative value shifts it down.  The
175 unit of this distance is the half staff space.")
176
177 (translator-property-description 'combineParts boolean? "try to combine parts?")
178 (translator-property-description 'connectArpeggios boolean? " If
179 set, connect all arpeggios that are found.  In this way, you can make
180 arpeggios that cross staves.
181 ")
182 (translator-property-description 'createKeyOnClefChange boolean? "Print a key signature whenever the clef is changed.")
183 (translator-property-description 'crescendoText markup? "Text to print at start of non-hairpin crecscendo, ie: @samp{cresc.}")
184 (translator-property-description 'crescendoSpanner symbol? "Type of spanner to be used for crescendi.  One of: @samp{hairpin}, @samp{line}, @samp{dashed-line}, @samp{dotted-line}.  If unset, hairpin type is used.")
185 (translator-property-description 'decrescendoText markup? "Text to print at start of non-hairpin decrecscendo, ie: @samp{dim.}")
186 (translator-property-description 'currentBarNumber integer? "Contains the current barnumber. This property is incremented at
187 every barline.
188 ")
189 (translator-property-description 'currentCommandColumn ly:grob? "Grob that is X-parent to all current breakable (clef, key signature, etc.) items.")
190 (translator-property-description 'currentMusicalColumn ly:grob? "Grob that is X-parent to all non-breakable items (note heads, lyrics, etc.).")
191 (translator-property-description 'defaultBarType string? "Sets the default type of bar line.  Available bar types: [FIXME];
192
193 This variable is typically read at Score level, so overriding
194 Staff.defaultBarType will have no effect.
195
196 ")
197 (translator-property-description 'devNullThread symbol? "User control of Thread_devnull_engraver: one of
198 @table @samp
199 @item (), or unset
200 Behave in normal way: remove one set of grobs when in unisolo.
201 @item always:
202 Remove any grob that comes along.
203 @item never:
204 Do nothing.
205 @end table
206 ")
207 (translator-property-description 'devNullVoice symbol? "User control of Voice_devnull_engraver: one of
208 @table @samp
209 @item (), or unset
210 Behave in normal way: remove spanners when in unisolo.
211 @item always:
212 Remove any spanners that come along.
213 @item never:
214 Do nothing.
215 @end table
216 ")
217 (translator-property-description 'decrescendoSpanner symbol? "Type of spanner to be used for decrescendi.  One of: @samp{hairpin}, @samp{line}, @samp{dashed-line}, @samp{dotted-line}.  If unset, hairpin type is used.")
218
219 (translator-property-description 'dynamicAbsoluteVolumeFunction procedure? "
220 [DOCUMENT-ME]
221 ")
222 (translator-property-description 'explicitClefVisibility procedure? "visibility-lambda function for clef changes.")
223
224
225
226 (translator-property-description 'explicitKeySignatureVisibility
227 procedure? "visibility-lambda function for explicit Key changes;
228 \override of #'break-visibility will set the visibility for normal
229 (ie. at the start of the line) key signatures.")
230
231 (translator-property-description 'extraNatural boolean? "Whether to typeset an
232 extra natural sign before accidentals changing from a non-natural to 
233 another non-natural.
234 ")
235
236 (translator-property-description 'finalizations list? "List of expressions to evaluate before proceeding to next time step. Internal variable.")
237 (translator-property-description 'followVoice boolean?
238                                  "if set, note heads are tracked  across staff switches by a thin line")
239 (translator-property-description 'fontSize integer?
240                                  "Used to set the relative size of all grobs
241 in a context. This is done using the @code{Font_size_engraver}.")
242
243 (translator-property-description 'forceClef boolean? "Show clef symbol, even if it hasn't changed. Only active for the first clef after the property is set, not for the full staff.")
244 (translator-property-description 'graceAccidentalSpace number? "amount space to alot for an accidental")
245 (translator-property-description 'graceAlignPosition ly:dir? "put the grace note before or after the main note?")
246 (translator-property-description 'highStringOne boolean? "Whether the 1st string is the string with
247 highest pitch on the instrument (used by the automatic string selector).")
248 (translator-property-description 'instr markup? "see @code{instrument}")
249 (translator-property-description 'instrument markup? " If @code{Instrument_name_engraver}
250 @cindex Instrument_name_engraver
251  is
252     added to the Staff translator, then the @code{instrument} property
253     is used to label the first line of the staff and the @code{instr}
254     property is used to label subsequent lines.  If the
255     @code{midiInstrument} property is not set, then @code{instrument}
256     is used to determine the instrument for MIDI output.")
257
258 (translator-property-description 'instrumentEqualizer procedure? "[DOCUMENT-ME]")
259 (translator-property-description 'instrumentSupport list? "
260 list of grobs to attach instrument name to. 
261 ")                               
262 (translator-property-description 'keyAccidentalOrder list? "
263 Alist that defines in what order  alterations should be printed.
264 The format is (NAME . ALTER), where NAME is from 0 .. 6 and ALTER from  -1, 1.
265 ")
266 (translator-property-description 'keySignature list? "The current key signature. This is an alist containing (NAME . ALTER) or ((OCTAVE . NAME) . ALTER) or ((OCTAVE . NAME) . (ALTER . BARNUMBER)) pairs, where NAME is from 0.. 6 and ALTER from -2,-1,0,1,2. The optional barnumber contains the number of the measure of the accidental. FIXME: describe broken tie entries.")
267
268 (translator-property-description 'lastKeySignature list? "Last key
269 signature before a key signature change.")
270
271 (translator-property-description 'localKeySignature list? "the key
272 signature at this point in the measure.  The format is the same as for keySignature. Is reset at every bar line."
273
274 (translator-property-description 'localKeySignatureChanges list? "Experimental.
275  [DOCME]")
276 (translator-property-description 'measureLength ly:moment? "Length of one
277 measure in the current time signature last?")
278 (translator-property-description 'measurePosition ly:moment? " How much
279 of the current measure (measured in whole notes) have we had.  This
280 can be set manually to create incomplete measures (anacrusis, upbeat),
281 the start of the music.
282 ")
283 (translator-property-description 'melismaBusy boolean? "Signifies
284 whether a melisma is active. This can be used to signal melismas on
285 top of those automatically detected. ")
286 (translator-property-description 'melismaEngraverBusy boolean? "See melismaBusy. This is set automatically.")
287 (translator-property-description 'midiInstrument string? "Name of the
288 MIDI instrument to use ")
289 (translator-property-description 'midiMinimumVolume number? "[DOCUMENT-ME]")
290 (translator-property-description 'midiMaximumVolume number? "[DOCUMENT-ME]")
291 (translator-property-description 'minimumFret number? "The tablature
292 auto string-selecting mechanism selects the highest string with a fret
293 not less than minimumFret")
294 (translator-property-description 'autoBeaming boolean? "If set to true
295 then beams are generated automatically.")
296 (translator-property-description 'noDirection boolean? "Don't set directions by a2-engraver when part-combining.")
297 (translator-property-description 'oneBeat ly:moment? "  How long does one beat in the current time signature last?")
298 (translator-property-description 'othersolo boolean? "FIXME")
299 (translator-property-description 'pedalSustainStrings list? "List of   string to print for sustain-pedal. Format is
300  (UP UPDOWN DOWN), where each of the three is the string to print when
301 this is done with the pedal.")
302 (translator-property-description 'pedalUnaCordaStrings list? "see pedalSustainStrings.")
303 (translator-property-description 'pedalSostenutoStrings list? "see pedalSustainStrings.")
304
305 (translator-property-description 'phrasingPunctuation string? "")
306 (translator-property-description 'rehearsalMark number-or-string? "")
307 (translator-property-description 'regularSpacingDelta ly:moment? "TODO")
308 (translator-property-description 'repeatCommands list? "This property is read to find any command of the form (volta . X), where X is a string or #f")
309 (translator-property-description 'scriptDefinitions list? "
310 Description of scripts. This is used by Script_engraver for typesetting note-super/subscripts. See @file{scm/script.scm} for more information
311 ")
312
313 (translator-property-description 'restNumberThreshold number?
314                                  "If a multimeasure rest takes less
315 than this number of measures, no number is printed. ")
316
317 (translator-property-description 'scriptHorizontal boolean? "  Put
318 scripts left or right of note heads.  Support for this is limited.
319 Accidentals will collide with scripts.
320 ")
321
322 (translator-property-description 'skipBars boolean? " Set to true to
323 skip the empty bars that are produced by multimeasure notes and rests.
324 These bars will not appear on the printed output.  If not set (the
325 default) multimeasure notes and rests expand into their full length,
326 printing the appropriate number of empty bars so that synchronization
327 with other voices is preserved.
328
329
330 @example
331 @@lilypond[fragment,verbatim,center]
332 r1 r1*3 R1*3  \\\\property Score.skipBars= ##t r1*3 R1*3
333
334 @@end lilypond
335 @end example
336
337 ")
338 (translator-property-description 'skipTypesetting boolean?
339                                  "When true, all no typesetting is done at
340 this moment, causing  the interpretation phase to go a lot faster. This can
341 help with debugging large scores.")
342 (translator-property-description 'slurMelismaBusy boolean? "Signal a slur if automaticMelismata is set.")
343 (translator-property-description 'solo boolean? "set if solo is detected by the part combiner.")
344 (translator-property-description 'soloADue boolean? "set Solo/A due texts in the part combiner?.")
345 (translator-property-description 'soloIIText string? "text for begin of solo for voice ``two'' when part-combining.")
346 (translator-property-description 'soloText string? "text for begin of solo when part-combining.")
347 (translator-property-description 'sparseTies boolean? "only create one tie per chord.")
348 (translator-property-description 'splitInterval number-pair? "part-combiner will separate its two voices (or threads) when interval between the two voices is contained in this range.")
349 (translator-property-description 'split-interval boolean? "set if part-combiner separated voices based on splitInterval.")
350 (translator-property-description 'squashedPosition integer? " Vertical position of
351 squashing for Pitch_squash_engraver.")
352 (translator-property-description 'stringOneTopmost boolean? "Whether the 1st string is printed on the
353 top line of the tablature.")
354 (translator-property-description 'stavesFound list? "list of all staff-symbols found.")
355 (translator-property-description 'stanza markup? "Stanza `number' to print at start of a verse. Use in LyricsVoice context.")
356
357
358 (translator-property-description 'stemLeftBeamCount integer? "
359 Specify the number of beams to draw on the left side of the next note.
360 Overrides automatic beaming.  The value is only used once, and then it
361 is erased.
362 .")
363 (translator-property-description 'stemRightBeamCount integer? "idem, for the right side.")
364
365 (translator-property-description 'stz markup? "Abbreviated form for a stanza, see also Stanza property.")
366 (translator-property-description 'subdivideBeams boolean? "If set, multiple beams will be subdivided at beat
367 positions - by only drawing one beam over the beat.")
368 (translator-property-description 'systemStartDelimiter symbol? "Which grob to make for the start of the system/staff?")
369 (translator-property-description 'tablatureFormat procedure?
370                                  "Function formatting a tab notehead; it takes
371 a string number, a list of string tunings and Pitch object. It returns the text as a string.")
372
373 (translator-property-description 'textNonEmpty boolean? " If set
374 to true then text placed above or below the staff is not assumed to
375 have zero width.  @code{\fatText} and @code{\emptyText} are predefined
376 settings.
377 .")
378 (translator-property-description 'tieMelismaBusy boolean? "Signal ties when automaticMelismata is set.")
379 (translator-property-description 'timeSignatureFraction number-pair? "
380 pair of numbers,  signifying the time signature. For example #'(4 . 4) is a 4/4time signature.")
381 (translator-property-description 'timing boolean? " Keep administration of measure length, position, bar number, etc?
382 Switch off for cadenzas.")
383 (translator-property-description 'transposing integer? "Transpose the MIDI output.  Set this property to the number of half-steps to transpose by.")
384 (translator-property-description 'tremoloFlags integer? "Number of tremolo flags to add if none is specified.")
385 (translator-property-description 'tupletNumberFormatFunction procedure?
386                                  "Function taking a music as input, producing a string. This function is called to determine the text to print on a tuplet bracket.")
387
388 (translator-property-description 'tupletInvisible boolean? "
389     If set to true, tuplet bracket creation is switched off
390 entirely. This has the same effect as setting both
391 @code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
392 @code{#f}, but as this does not even create any grobs, this setting
393 uses less memory and time.")
394 (translator-property-description 'tupletSpannerDuration ly:moment? "
395 Normally a tuplet bracket is as wide as the
396 @code{  imes} expression that gave rise to it. By setting this
397 property, you can make brackets last shorter. Example
398
399 @example
400 @@lilypond[verbatim,fragment]
401 context Voice   imes 2/3 @{
402   property Voice.tupletSpannerDuration = #(ly:make-moment 1 4)
403   [c8 c c] [c c c]
404 @}
405 @@end lilypond
406 @end example
407 .")
408 (translator-property-description 'unirhythm boolean? "set if unirhythm is detected by the part combiner.")
409 (translator-property-description 'unisilence boolean? "set if unisilence is detected by the part combiner.")
410 (translator-property-description 'unison boolean? "set if unisono is detected  by the part combiner. .")
411 (translator-property-description 'verticalAlignmentChildCallback
412 procedure? "what callback to add to children of a vertical alignment.
413 It determines what alignment procedure is used on the alignment
414 itself.  .")
415 (translator-property-description
416  'voltaOnThisStaff boolean?
417  "Normally, volta brackets are put only on the topmost staff. Setting this variable to true, will force a bracket to be on this staff as well.")
418 (translator-property-description 'voltaSpannerDuration ly:moment? "maximum duration of the volta bracket.
419
420     Set to a duration to control the size of the brackets printed by
421 @code{\\alternative}.  It specifies the number of whole notes duration
422 to use for the brackets.  This can be used to shrink the length of
423 brackets in the situation where one alternative is very large.  It may
424 have odd effects if the specified duration is longer than the music
425 given in an @code{\\alternative}.
426 .")
427 (translator-property-description 'whichBar string?
428                                  "This property is read to determine what type of barline to create.
429
430 Example:
431 @example
432 \\property Staff.whichBar = \"|:\"
433 @end example
434
435 This will create a start-repeat bar in this staff only.
436
437 If not set explicitly (by property or @code{\bar}), this is set
438 according to values of @code{defaultBarType}, @code{barAlways},
439 @code{barNonAuto} and @code{measurePosition}.
440
441 Valid values are described in @ref{(lilypond-internals)bar-line-interface}.
442
443 .")
444 (translator-property-description 'stringTunings list? "The tablature strings tuning. Must be a list of the different semitons pitch of each string (starting by the lower one).")
445