1 ;;;; translator-property-description.scm -- part of backend documentation
3 ;;;; source file of the GNU LilyPond music typesetter
5 ;;;; (c) 1998--2003 Han-Wen Nienhuys <hanwen@cs.uu.nl>
6 ;;;; Jan Nieuwenhuizen <janneke@gnu.org>
9 (define-public all-translation-properties '())
11 (define (translator-property-description symbol type? description)
12 (if (not (equal? #f (object-property symbol 'translation-doc)))
14 (ly:warn (string-append "Redefining " (symbol->string symbol) "\n"))
18 (set-object-property! symbol 'translation-type? type?)
19 (set-object-property! symbol 'translation-doc description)
20 (set! all-translation-properties (cons symbol all-translation-properties))
25 (translator-property-description 'acceptHashTable vector? "Internal
26 variable: store table with MusicName to Engraver entries.")
27 (translator-property-description 'acknowledgeHashTable vector?
28 "Internal variable: store interface to engraver smob table for current
29 context. Don't mess with this.")
30 (translator-property-description 'aDueText string? "text for begin of a due")
31 (translator-property-description 'alignBassFigureAccidentals boolean?
32 "If true, then the accidentals are aligned in bass figure context.")
34 (translator-property-description 'allowBeamBreak boolean?
35 "If true allow line breaks during beams.")
36 (translator-property-description 'associatedVoice string? "Name of the
37 Voice that has the melody for this LyricsVoice.")
38 (translator-property-description 'associatedVoiceContext ly:context? "The context object of the Voice that has the melody for this LyricsVoice.")
39 (translator-property-description 'autoBeamSettings list? "Specifies
40 when automatically generated beams should begin and end. The elements
45 function shortest-duration-in-beam time-signature
49 function = begin or end
50 shortest-duration-in-beam = numerator denominator; eg: 1 16
51 time-signature = numerator denominator, eg: 4 4
53 unspecified or wildcard entries for duration or time-signature
56 The user can override beam begin or end time by pushing a wildcard entries
57 '(begin * * * *) or '(end * * * *) resp., eg:
59 property Voice.autoBeamSettings push #'(end * * * *) = #(ly:make-moment 1 4)
63 ((end * * 3 2) . ,(ly:make-moment 1 2))
64 ((end 1 16 3 2) . ,(ly:make-moment 1 4))
65 ((end 1 32 3 2) . ,(ly:make-moment 1 8))
73 (translator-property-description 'autoAccidentals list? "List of
74 different ways to typeset an accidental. All algorithms in the list
75 are tried, and the one returning the most accidentals is used.
76 Each entry is either a symbol containg a context name or a name-value
77 pair containing an algorithm-description.
78 The list must begin with a symbol (context name).
79 The symbols denote in which context THE FOLLOWING algorithms (until next symbol)
80 will be interpreted. All notes in the interpretation context will share accidentals.
81 The contexts must be stated in order, innermost first.
85 This is the default algorithm. Accidentals are typeset if the note changes
86 the accidental of that note in that octave. Accidentals lasts to the end of the measure
87 and then as many measures as specified in the value. I.e. 1 means to the end
88 of next measure, -1 means to the end of previous measure (that is: no duration at all), etc. #t means forever.
90 Accidentals are typeset if the note is different from
91 the previous note on the same pitch in any octave. The value has same meaning as in
95 (translator-property-description 'autoBeaming boolean? "If set to true
96 then beams are generated automatically.")
98 (translator-property-description 'autoCautionaries list? "List similar to
99 autoAccidentals, but it controls cautionary accidentals rather than
100 normal ones. Both lists are tried, and the one giving the most accidentals
101 wins. In case of draw, a normal accidental is typeset.
103 (translator-property-description 'automaticBars boolean? " If set to true then bar lines will not be printed
104 automatically; they must be explicitly created with @code{bar}
105 keywords. Unlike with the @code{cadenza} keyword, measures are
106 still counted. Bar generation will resume according to that
107 count if this property is set to zero.
110 (translator-property-description 'barAlways boolean? "If set to true a bar line is drawn after each note.
112 (translator-property-description 'barCheckLastFail ly:moment? "Where in the measurze did the last barcheck fail?")
114 (translator-property-description 'barCheckSynchronize boolean? "If
115 true then reset measurePosition when finding a barcheck. Turn off when
116 using barchecks in polyphonic music.")
117 (translator-property-description 'barNumberVisibility procedure? "Procedure that takes an int and returns whether the corresponding bar number should be printed")
118 (translator-property-description 'bassFigureFormatFunction procedure? "DOCME")
119 (translator-property-description 'beamMelismaBusy boolean? "Signal if a beam is present.")
120 (translator-property-description 'beatLength ly:moment? "The length of one beat in this time signature.")
121 (translator-property-description 'beatGrouping list?
122 "List of beatgroups. Eg. in 5/8 time #(list 2 3).")
125 (translator-property-description 'breakableSeparationItem ly:grob?
126 "The breakable items in this time step, for this staff.")
128 (translator-property-description 'breakAlignOrder list? "Defines the order in which
129 prefatory matter (clefs, key signatures) appears, eg. this puts the
130 key signatures after the bar lines:
133 \\property Score.breakAlignOrder = #'(
143 (translator-property-description 'busyGrobs list? "
144 a queue of (END-MOMENT . GROB) conses. This is for internal (C++) use only.
145 Use at your own risk. This property contains the grobs for which END-MOMENT >= NOW.
148 (translator-property-description 'centralCPosition number? "Place of
149 the central C, measured in half staffspaces. Usually determined by
150 looking at clefPosition and clefGlyph.")
152 (translator-property-description
153 'changeMoment moment-pair?
154 "duration that voices are examined for differences, when
155 part-combining. Usually unset or zero when combining threads into one
156 voice, and 1 (or the duration of one measure) when combining voices
159 (translator-property-description
160 'chordNameFunction procedure?
161 "The function that converts lists of pitches to chord names.")
162 (translator-property-description
163 'chordNoteNamer procedure?
164 "Function that converts from a pitch object to a text markup. Used for single pitches.")
165 (translator-property-description
166 'chordRootNamer procedure?
167 "Function that converts from a pitch object to a text markup. Used for chords.")
168 (translator-property-description
169 'chordNameExceptions list?
170 "Alist of chord exceptions. Contains (CHORD . MARKUP) entries.")
171 (translator-property-description
172 'chordNameExceptionsFull list?
173 "Alist of chord exceptions. Contains (CHORD . (MARKUP)) entries.")
174 (translator-property-description
175 'chordNameExceptionsPartial list?
176 "Alist of partial chord exceptions. Contains (CHORD . (PREFIX-MARKUP SUFFIX-MARKUP)) entries.")
177 (translator-property-description
178 'chordNameSeparator markup?
179 "The markup object used to separate parts of a chord name.")
181 (translator-property-description 'chordChanges boolean? "Only show changes in chords scheme?")
182 (translator-property-description 'clefGlyph string? "Name of the symbol within the music font")
183 (translator-property-description 'clefOctavation integer? "Add
184 this much extra octavation. Values of 7 and -7 are common.")
186 (translator-property-description 'clefPosition number? "Where should
187 the center of the clef symbol go? On systems with an odd number of
188 stafflines, the value 0 puts the clef on the middle staffline; a
189 positive value shifts it up, a negative value shifts it down. The
190 unit of this distance is the half staff space.")
192 (translator-property-description 'combineParts boolean? "try to combine parts?")
193 (translator-property-description 'connectArpeggios boolean? " If
194 set, connect all arpeggios that are found. In this way, you can make
195 arpeggios that cross staves.
197 (translator-property-description 'createKeyOnClefChange boolean? "Print a key signature whenever the clef is changed.")
198 (translator-property-description 'crescendoText markup? "Text to print at start of non-hairpin crecscendo, ie: @samp{cresc.}")
199 (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.")
200 (translator-property-description 'decrescendoText markup? "Text to print at start of non-hairpin decrecscendo, ie: @samp{dim.}")
201 (translator-property-description 'currentBarNumber integer? "Contains the current barnumber. This property is incremented at
204 (translator-property-description 'currentCommandColumn ly:grob? "Grob that is X-parent to all current breakable (clef, key signature, etc.) items.")
205 (translator-property-description 'currentMusicalColumn ly:grob? "Grob that is X-parent to all non-breakable items (note heads, lyrics, etc.).")
206 (translator-property-description 'defaultBarType string? "Sets the default type of bar line. Available bar types: [FIXME];
208 This variable is typically read at Score level, so overriding
209 Staff.defaultBarType will have no effect.
212 (translator-property-description 'devNullThread symbol? "User control of Thread_devnull_engraver: one of
215 Behave in normal way: remove one set of grobs when in unisolo.
217 Remove any grob that comes along.
222 (translator-property-description 'devNullVoice symbol? "User control of Voice_devnull_engraver: one of
225 Behave in normal way: remove spanners when in unisolo.
227 Remove any spanners that come along.
232 (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.")
234 (translator-property-description 'dynamicAbsoluteVolumeFunction procedure? "
237 (translator-property-description 'explicitClefVisibility procedure? "visibility-lambda function for clef changes.")
239 (translator-property-description 'explicitKeySignatureVisibility
240 procedure? "visibility-lambda function for explicit Key changes;
241 \\override of #'break-visibility will set the visibility for normal
242 (ie. at the start of the line) key signatures.")
244 (translator-property-description 'extraNatural boolean? "Whether to typeset an
245 extra natural sign before accidentals changing from a non-natural to
249 (translator-property-description 'extraVerticalExtent number-pair?
250 "extra vertical extent, same format as MinimumVerticalExtent")
253 (translator-property-description 'finalizations list? "List of expressions to evaluate before proceeding to next time step. Internal variable.")
254 (translator-property-description 'followVoice boolean?
255 "if set, note heads are tracked across staff switches by a thin line")
256 (translator-property-description 'fontSize number?
257 "Used to set the relative size of all grobs
258 in a context. This is done using the @code{Font_size_engraver}.")
260 (translator-property-description
261 'fingeringOrientations list?
262 "List of symbols, containing left, right, up and/or down. This list determines where fingerings are put wrt. to the chord being fingered.")
264 (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.")
266 (translator-property-description 'graceSettings vector?
267 "Overrides for grace notes. This
268 property should be manipulated through the @code{add-grace-property}
271 (translator-property-description 'highStringOne boolean? "Whether the
272 1st string is the string with highest pitch on the instrument (used by
273 the automatic string selector).")
275 (translator-property-description 'ignoreMelismata boolean?
276 "Ignore melismata for this @ref{LyricsVoice}.")
277 (translator-property-description 'instr markup? "see @code{instrument}")
278 (translator-property-description 'instrument markup? " If @code{Instrument_name_engraver}
279 @cindex Instrument_name_engraver
281 added to the Staff translator, then the @code{instrument} property
282 is used to label the first line of the staff and the @code{instr}
283 property is used to label subsequent lines. If the
284 @code{midiInstrument} property is not set, then @code{instrument}
285 is used to determine the instrument for MIDI output.")
287 (translator-property-description 'instrumentEqualizer procedure? "[DOCUMENT-ME]")
288 (translator-property-description 'instrumentSupport list? "
289 list of grobs to attach instrument name to.
291 (translator-property-description 'keyAccidentalOrder list? "
292 Alist that defines in what order alterations should be printed.
293 The format is (NAME . ALTER), where NAME is from 0 .. 6 and ALTER from -1, 1.
295 (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.")
297 (translator-property-description 'lastKeySignature list? "Last key
298 signature before a key signature change.")
300 (translator-property-description 'localKeySignature list? "the key
301 signature at this point in the measure. The format is the same as for keySignature. Is reset at every bar line."
303 (translator-property-description 'localKeySignatureChanges list? "Experimental.
306 (translator-property-description 'majorSevenSymbol markup? "How should
307 the major7 be formatted in a chord name?")
308 (translator-property-description 'markFormatter procedure? "Procedure
309 taking as arguments context and rehearsal mark. It should return the
310 formatted mark as a markup object.")
312 (translator-property-description 'measureLength ly:moment? "Length of one
313 measure in the current time signature last?")
314 (translator-property-description 'measurePosition ly:moment? "How much
315 of the current measure (measured in whole notes) have we had. This
316 can be set manually to create incomplete measures (anacrusis, upbeat),
317 the start of the music.
319 (translator-property-description 'melismaBusy boolean? "Signifies
320 whether a melisma is active. This can be used to signal melismas on
321 top of those automatically detected. ")
322 (translator-property-description 'melismaBusyProperties list?
323 "List of properties (symbols) to
324 determine whether a melisma is playing. Setting this property will
325 influence how lyrics are aligned to notes. For example, if set to
326 @code{#'(melismaBusy beamMelismaBusy)}, only manual melismata
327 (i.e. setting @code{melismaBusy} to @code{#t}) and manual beams are
328 considered. Possible values include @code{melismaBusy},
329 @code{slurMelismaBusy}, @code{tieMelismaBusy}, and
330 @code{beamMelismaBusy}")
333 (translator-property-description 'metronomeMarkFormatter procedure?
334 "How to produce a metronome markup.
335 Called with 2 arguments, event and context.")
336 (translator-property-description 'midiInstrument string? "Name of the
337 MIDI instrument to use ")
338 (translator-property-description 'midiMinimumVolume number? "[DOCUMENT-ME]")
339 (translator-property-description 'midiMaximumVolume number? "[DOCUMENT-ME]")
340 (translator-property-description 'minimumFret number? "The tablature
341 auto string-selecting mechanism selects the highest string with a fret
342 not less than minimumFret")
343 (translator-property-description 'minimumVerticalExtent number-pair?
344 "minimum vertical extent, same format as VerticalExtent")
345 (translator-property-description 'recordEventSequence procedure?
346 "Upon termination of this context,
347 this function is called with current context and a list of music
348 objects. The list of contains entries with start times, music objects
349 and whether they're processed in this context.")
351 (translator-property-description 'noDirection boolean? "Don't set directions by a2-engraver when part-combining.")
352 (translator-property-description
353 'originalCentralCPosition integer?
354 "Used for temporary overriding central C in octavation brackets. ")
355 (translator-property-description 'othersolo boolean? "FIXME")
356 (translator-property-description 'ottavation string? "If set, the text
357 for an 8va spanner. Changing this implies a new text spanner. ")
358 (translator-property-description 'pedalSustainStrings list? "List of string to print for sustain-pedal. Format is
359 (UP UPDOWN DOWN), where each of the three is the string to print when
360 this is done with the pedal.")
361 (translator-property-description 'pedalUnaCordaStrings list? "see pedalSustainStrings.")
362 (translator-property-description 'pedalSostenutoStrings list? "see pedalSustainStrings.")
363 (translator-property-description 'pedalSustainStyle symbol? "A symbol
364 that indicates how to print sustain pedals: text, bracket or mixed
366 (translator-property-description 'pedalUnaCordaStyle symbol? "see pedalSustainStyle.")
367 (translator-property-description 'pedalSostenutoStyle symbol? "see pedalSustainStyle.")
369 (translator-property-description 'rehearsalMark integer? "The
370 last rehearsal mark printed.")
371 (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")
372 (translator-property-description 'scriptDefinitions list? "
373 Description of scripts. This is used by Script_engraver for typesetting note-super/subscripts. See @file{scm/script.scm} for more information
376 (translator-property-description 'restNumberThreshold number?
377 "If a multimeasure rest takes less
378 than this number of measures, no number is printed. ")
380 (translator-property-description 'scriptHorizontal boolean? " Put
381 scripts left or right of note heads. Support for this is limited.
382 Accidentals will collide with scripts.
384 (translator-property-description 'skipBars boolean? "If set to true, then
385 skip the empty bars that are produced by multimeasure notes and rests.
386 These bars will not appear on the printed output. If not set (the
387 default) multimeasure notes and rests expand into their full length,
388 printing the appropriate number of empty bars so that synchronization
389 with other voices is preserved.
393 @@lilypond[fragment,verbatim,center]
394 r1 r1*3 R1*3 \\\\property Score.skipBars= ##t r1*3 R1*3
400 (translator-property-description 'skipTypesetting boolean?
401 "When true, all no typesetting is done at
402 this moment, causing the interpretation phase to go a lot faster. This can
403 help with debugging large scores.")
404 (translator-property-description 'slurMelismaBusy boolean? "Signal if a slur is present.")
405 (translator-property-description 'solo boolean? "set if solo is detected by the part combiner.")
406 (translator-property-description 'soloADue boolean? "set Solo/A due texts in the part combiner?.")
407 (translator-property-description 'soloIIText string? "text for begin of solo for voice ``two'' when part-combining.")
408 (translator-property-description 'soloText string? "text for begin of solo when part-combining.")
409 (translator-property-description 'sparseTies boolean? "only create one tie per chord.")
410 (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.")
411 (translator-property-description 'split-interval boolean? "set if part-combiner separated voices based on splitInterval.")
412 (translator-property-description 'squashedPosition integer? " Vertical position of
413 squashing for Pitch_squash_engraver.")
414 (translator-property-description 'stringOneTopmost boolean? "Whether the 1st string is printed on the
415 top line of the tablature.")
416 (translator-property-description 'stavesFound list? "list of all staff-symbols found.")
417 (translator-property-description 'stanza markup? "Stanza `number' to
418 print before the start of a verse. Use in LyricsVoice context.")
419 (translator-property-description 'stemLeftBeamCount integer? "
420 Specify the number of beams to draw on the left side of the next note.
421 Overrides automatic beaming. The value is only used once, and then it
424 (translator-property-description 'stemRightBeamCount integer? "idem, for the right side.")
425 (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).")
426 (translator-property-description 'subdivideBeams boolean? "If set, multiple beams will be subdivided at beat
427 positions - by only drawing one beam over the beat.")
428 (translator-property-description 'systemStartDelimiter symbol? "Which grob to make for the start of the system/staff? Set to @code{SystemStartBrace}, @code{SystemStartBracket} or @code{SystemStartBar}.")
429 (translator-property-description 'tablatureFormat procedure?
430 "Function formatting a tab notehead; it takes
431 a string number, a list of string tunings and Pitch object. It returns the text as a string.")
433 (translator-property-description 'tieMelismaBusy boolean? "Signal whether a tie is present.")
434 (translator-property-description 'timeSignatureFraction number-pair?
435 "pair of numbers, signifying the time signature. For example #'(4 . 4)
436 is a 4/4 time signature.")
438 (translator-property-description 'timing boolean? " Keep administration of measure length, position, bar number, etc?
439 Switch off for cadenzas.")
440 (translator-property-description 'tonic ly:pitch?
441 "The tonic of the current scale")
442 (translator-property-description 'transposing integer? "Transpose the MIDI output. Set this property to the number of half-steps to transpose by.")
443 (translator-property-description 'tremoloFlags integer? "Number of tremolo flags to add if none is specified.")
444 (translator-property-description 'tupletNumberFormatFunction procedure?
445 "Function taking a music as input, producing a string. This function is called to determine the text to print on a tuplet bracket.")
449 (translator-property-description 'tupletInvisible boolean? "
450 If set to true, tuplet bracket creation is switched off
451 entirely. This has the same effect as setting both
452 @code{tupletNumberVisibility} and @code{tupletBracketVisibility} to
453 @code{#f}, but as this does not even create any grobs, this setting
454 uses less memory and time.")
456 (translator-property-description 'tupletSpannerDuration ly:moment? "
457 Normally a tuplet bracket is as wide as the
458 @code{ imes} expression that gave rise to it. By setting this
459 property, you can make brackets last shorter. Example
462 @@lilypond[verbatim,fragment]
463 context Voice imes 2/3 @{
464 property Voice.tupletSpannerDuration = #(ly:make-moment 1 4)
470 (translator-property-description 'unirhythm boolean? "set if unirhythm is detected by the part combiner.")
471 (translator-property-description 'unisilence boolean? "set if unisilence is detected by the part combiner.")
472 (translator-property-description 'unison boolean? "set if unisono is detected by the part combiner. .")
473 (translator-property-description 'verticalAlignmentChildCallback
474 procedure? "what callback to add to children of a vertical alignment.
475 It determines what alignment procedure is used on the alignment
477 (translator-property-description 'verticalExtent number-pair? "hard
478 coded vertical extent. The format is a pair of dimensions, for
479 example, this sets the sizes of a staff to 10 (5+5) staffspaces high.
482 property Staff.verticalExtent = #(-5.0 . 5.0)
485 VerticalExtent, MinimumVerticalExtent and ExtraVerticalExtent are
486 predefined in all relevant contexts to @code{#f}, so they will not
489 Note that these VerticalExtents can only operate on vertical groups,
490 and therefore only work in contexts which contain an
491 @code{Axis_group_engraver}.
494 (translator-property-description 'voltaOnThisStaff boolean?
495 "Normally, volta brackets are put only on the topmost staff. Setting
496 this variable to true, will force a bracket to be on this staff as
499 (translator-property-description 'voltaSpannerDuration ly:moment? "maximum duration of the volta bracket.
501 Set to a duration to control the size of the brackets printed by
502 @code{\\alternative}. It specifies the number of whole notes duration
503 to use for the brackets. This can be used to shrink the length of
504 brackets in the situation where one alternative is very large. It may
505 have odd effects if the specified duration is longer than the music
506 given in an @code{\\alternative}.
508 (translator-property-description 'whichBar string?
509 "This property is read to determine what type of barline to create.
513 \\property Staff.whichBar = \"|:\"
516 This will create a start-repeat bar in this staff only.
518 If not set explicitly (by property or @code{\\bar}), this is set
519 according to values of @code{defaultBarType}, @code{barAlways},
520 @code{barNonAuto} and @code{measurePosition}.
522 Valid values are described in @ref{(lilypond-internals)bar-line-interface}.
527 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
529 (define-public default-melisma-properties '(melismaBusy slurMelismaBusy tieMelismaBusy beamMelismaBusy))