1 ;;;; define-context-properties.scm -- part of backend documentation
3 ;;;; source file of the GNU LilyPond music typesetter
5 ;;;; (c) 1998--2009 Han-Wen Nienhuys <hanwen@xs4all.nl>
6 ;;;; Jan Nieuwenhuizen <janneke@gnu.org>
9 (define-public all-translation-properties '())
11 (define (translator-property-description symbol type? description)
15 (string? description)))
16 (throw 'init-format-error))
19 (if (not (equal? #f (object-property symbol 'translation-doc)))
20 (ly:error (_ "symbol ~S redefined" symbol)))
22 (set-object-property! symbol 'translation-type? type?)
23 (set-object-property! symbol 'translation-doc description)
24 (set! all-translation-properties (cons symbol all-translation-properties))
28 (define-public all-user-translation-properties
31 (apply translator-property-description x))
36 (aDueText ,markup? "Text to print at a unisono passage.")
37 (alignAboveContext ,string? "Where to insert newly created context in
39 (alignBassFigureAccidentals ,boolean? "If true, then the accidentals
40 are aligned in bass figure context.")
41 (alignBelowContext ,string? "Where to insert newly created context in
43 (associatedVoice ,string? "Name of the @code{Voice} that has the
44 melody for this @code{Lyrics} line.")
45 (autoAccidentals ,list? "List of different ways to typeset an
48 For determining when to print an accidental, several different rules
49 are tried. The rule that gives the highest number of accidentals is
52 Each entry in the list is either a symbol or a procedure.
57 The symbol is the name of the context in which the following rules are to be
58 applied. For example, if @var{context} is @rinternals{Score} then all
59 staves share accidentals, and if @var{context} is @rinternals{Staff} then
60 all voices in the same staff share accidentals, but staves do not.
63 The procedure represents an accidental rule to be applied to the previously
66 The procedure takes the following arguments:
71 The current context to which the rule should be applied.
74 The pitch of the note to be evaluated.
77 The current bar number.
80 The current measure position.
84 The procedure returns a pair of booleans. The first states whether an extra
85 natural should be added. The second states whether an accidental should be
86 printed. @code{(#t . #f)} does not make sense.
89 (autoBeamCheck ,procedure? "A procedure taking three
90 arguments, @var{context}, @var{dir} [start/stop (-1 or 1)], and
91 @var{test} [shortest note in the beam]. A non-@code{#f} return value
92 starts or stops the auto beam.")
93 (autoBeaming ,boolean? "If set to true then beams are generated
95 (autoCautionaries ,list? "List similar to @code{autoAccidentals},
96 but it controls cautionary accidentals rather than normal ones. Both
97 lists are tried, and the one giving the most accidentals wins. In
98 case of draw, a normal accidental is typeset.")
99 (automaticBars ,boolean? "If set to false then bar lines will not
100 be printed automatically; they must be explicitly created with a
101 @code{\\bar} command. Unlike the @code{\\cadenzaOn} keyword, measures
102 are still counted. Bar line generation will resume according to that
103 count if this property is unset.")
106 (barAlways ,boolean? "If set to true a bar line is drawn after
108 (barCheckSynchronize ,boolean? "If true then reset
109 @code{measurePosition} when finding a bar check.")
110 (barNumberVisibility ,procedure? "A Procedure that takes an
111 integer and returns whether the corresponding bar number should be
113 (bassFigureFormatFunction ,procedure? "A procedure that is
114 called to produce the formatting for a @code{BassFigure} grob. It
115 takes a list of @code{BassFigureEvent}s, a context, and the grob to
117 (bassStaffProperties ,list? "An alist of property settings to
118 apply for the down staff of @code{PianoStaff}. Used by
119 @code{\\autochange}.")
120 (beamSettings ,list? "Specifies when automatically generated
121 beams should begin and end, as well as beam subdivision behavior.
122 See @ruser{Setting automatic beam
123 behavior} for more information.")
124 (beatLength ,ly:moment? "The length of one beat in this time
128 (chordChanges ,boolean? "Only show changes in chords scheme?")
129 (chordNameExceptions ,list? "An alist of chord exceptions.
130 Contains @code{(@var{chord} . @var{markup})} entries.")
131 (chordNameExceptionsFull ,list? "An alist of full chord
132 exceptions. Contains @code{(@var{chord} . @var{markup})} entries.")
133 (chordNameExceptionsPartial ,list? "An alist of partial chord
134 exceptions. Contains @code{(@var{chord} . (@var{prefix-markup}
135 @var{suffix-markup}))} entries.")
136 (chordNameFunction ,procedure? "The function that converts lists
137 of pitches to chord names.")
138 (chordNameSeparator ,markup? "The markup object used to
139 separate parts of a chord name.")
140 (chordNoteNamer ,procedure? "A function that converts from a pitch
141 object to a text markup. Used for single pitches.")
142 (chordPrefixSpacer ,number? "The space added between the root
143 symbol and the prefix of a chord name.")
144 (chordRootNamer ,procedure? "A function that converts from a pitch
145 object to a text markup. Used for chords.")
146 (clefGlyph ,string? "Name of the symbol within the music font.")
147 (clefOctavation ,integer? "Add this much extra octavation.
148 Values of 7 and -7 are common.")
149 (clefPosition ,number? "Where should the center of the clef
150 symbol go, measured in half staff spaces from the center of the
152 (completionBusy ,boolean? "Whether a completion-note head is playing.")
153 (connectArpeggios ,boolean? "If set, connect arpeggios across
155 (countPercentRepeats ,boolean? "If set, produce counters for
157 (createKeyOnClefChange ,boolean? "Print a key signature whenever
158 the clef is changed.")
159 (createSpacing ,boolean? "Create @code{StaffSpacing} objects?
160 Should be set for staves.")
161 (crescendoSpanner ,symbol? "The type of spanner to be used for
162 crescendi. Available values are @samp{hairpin} and @samp{text}. If unset,
163 a hairpin crescendo is used.")
164 (crescendoText ,markup? "The text to print at start of non-hairpin
165 crescendo, i.e., @samp{cresc.}.")
166 (currentBarNumber ,integer? "Contains the current barnumber.
167 This property is incremented at every bar line.")
170 (decrescendoSpanner ,symbol? "The type of spanner to be used for
171 decrescendi. Available values are @samp{hairpin} and @samp{text}. If
172 unset, a hairpin decrescendo is used.")
173 (decrescendoText ,markup? "The text to print at start of
174 non-hairpin decrescendo, i.e., @samp{dim.}.")
175 (defaultBarType ,string? "Set the default type of bar line. See
176 @code{whichBar} for information on available bar types.
178 This variable is read by @rinternals{Timing_translator} at
179 @rinternals{Score} level.")
180 (doubleRepeatType ,string? "Set the default bar line for double
182 (doubleSlurs ,boolean? "If set, two slurs are created for every
183 slurred note, one above and one below the chord.")
184 (drumPitchTable ,hash-table? "A table mapping percussion
185 instruments (symbols) to pitches.")
186 (drumStyleTable ,hash-table? "A hash table which maps drums to
187 layout settings. Predefined values: @samp{drums-style},
188 @samp{timbales-style}, @samp{congas-style}, @samp{bongos-style}, and
189 @samp{percussion-style}.
191 The layout style is a hash table, containing the drum-pitches (e.g.,
192 the symbol @samp{hihat}) as keys, and a list
193 @code{(@var{notehead-style} @var{script} @var{vertical-position})} as
197 (explicitClefVisibility ,vector? "@samp{break-visibility}
198 function for clef changes.")
199 (explicitKeySignatureVisibility ,vector? "@samp{break-visibility}
200 function for explicit key changes. @samp{\\override} of the
201 @code{break-visibility} property will set the visibility for normal
202 (i.e., at the start of the line) key signatures.")
203 (extendersOverRests ,boolean? "Whether to continue extenders as
205 (extraNatural ,boolean? "Whether to typeset an extra natural sign
206 before accidentals changing from a non-natural to another
210 (figuredBassAlterationDirection ,ly:dir? "Where to put alterations
211 relative to the main figure.")
212 (figuredBassCenterContinuations ,boolean? "Whether to vertically
213 center pairs of extender lines. This does not work with three or more
215 (figuredBassFormatter ,procedure? "A routine generating a markup
217 (figuredBassPlusDirection ,ly:dir? "Where to put plus signs
218 relative to the main figure.")
219 (fingeringOrientations ,list? "A list of symbols, containing
220 @samp{left}, @samp{right}, @samp{up} and/or @samp{down}. This list
221 determines where fingerings are put relative to the chord being
223 (firstClef ,boolean? "If true, create a new clef when starting a
225 (followVoice ,boolean? "If set, note heads are tracked across
226 staff switches by a thin line.")
227 (fontSize ,number? "The relative size of all grobs in a context.")
228 (forbidBreak ,boolean? "If set to @code{##t}, prevent a line break
230 (forceClef ,boolean? "Show clef symbol, even if it has not
231 changed. Only active for the first clef after the property is set, not
232 for the full staff.")
235 (gridInterval ,ly:moment? "Interval for which to generate
239 (harmonicAccidentals ,boolean? "If set, harmonic notes in chords
241 (harmonicDots ,boolean? "If set, harmonic notes in dotted chords get
243 (highStringOne ,boolean? "Whether the first string is the string
244 with highest pitch on the instrument. This used by the automatic
245 string selector for tablature notation.")
248 (ignoreBarChecks ,boolean? "Ignore bar checks.")
249 (ignoreFiguredBassRest ,boolean? "Don't swallow rest events.")
250 (ignoreMelismata ,boolean? "Ignore melismata for this
251 @rinternals{Lyrics} line.")
252 (implicitBassFigures ,list? "A list of bass figures that are not
253 printed as numbers, but only as extender lines.")
254 (implicitTimeSignatureVisibility ,vector? "break visibility for
255 the default time signature.")
256 (instrumentCueName ,markup? "The name to print if another
257 instrument is to be taken.")
258 (instrumentEqualizer ,procedure? "A function taking a string
259 (instrument name), and returning a @code{(@var{min} . @var{max})} pair
260 of numbers for the loudness range of the instrument.")
261 (instrumentName ,markup? "The name to print left of a staff. The
262 @code{instrument} property labels the staff in the first system, and
263 the @code{instr} property labels following lines.")
264 ;; the definition is reversed wrt traditional transposition
265 ;; otherwise \transpose { \transposition .. } won't work
266 (instrumentTransposition ,ly:pitch? "Define the transposition of
267 the instrument. Its value is the pitch that sounds like middle@tie{}C.
268 This is used to transpose the MIDI output, and @code{\\quote}s.")
269 (internalBarNumber ,integer? "Contains the current barnumber.
270 This property is used for internal timekeeping, among others by the
271 @code{Accidental_engraver}.")
274 (keepAliveInterfaces ,list? "A list of symbols, signifying grob
275 interfaces that are worth keeping a staff with @code{remove-empty} set
277 (keyAlterationOrder ,list? "An alist that defines in what order
278 alterations should be printed. The format is @code{(@var{step}
279 . @var{alter})}, where @var{step} is a number from 0 to@tie{}6 and
280 @var{alter} from -2 (sharp) to 2 (flat).")
281 (keySignature ,list? "The current key signature. This is an alist
282 containing @code{(@var{step} . @var{alter})} or @code{((@var{octave} .
283 @var{step}) . @var{alter})}, where @var{step} is a number in the range
284 0 to@tie{}6 and @var{alter} a fraction, denoting alteration. For
285 alterations, use symbols, e.g. @code{keySignature = #`((6 . ,FLAT))}.")
288 (lyricMelismaAlignment ,ly:dir? "Alignment to use for a melisma syllable.")
291 (majorSevenSymbol ,markup? "How should the major 7th be formatted
293 (markFormatter ,procedure? "A procedure taking as arguments the
294 context and the rehearsal mark. It should return the formatted mark as
296 (maximumFretStretch ,number? "Don't allocate frets further than
297 this from specified frets.")
298 (measureLength ,ly:moment? "Length of one measure in the current
300 (measurePosition ,ly:moment? "How much of the current measure have
301 we had. This can be set manually to create incomplete measures.")
302 (melismaBusyProperties ,list? "A list of properties (symbols) to
303 determine whether a melisma is playing. Setting this property will
304 influence how lyrics are aligned to notes. For example, if set to
305 @code{#'(melismaBusy beamMelismaBusy)}, only manual melismata and
306 manual beams are considered. Possible values include
307 @code{melismaBusy}, @code{slurMelismaBusy}, @code{tieMelismaBusy}, and
308 @code{beamMelismaBusy}.")
309 (metronomeMarkFormatter ,procedure? "How to produce a metronome
310 markup. Called with four arguments: text, duration, count and context.")
311 (middleCClefPosition ,number? "The position of the middle C,
312 as determined only by the clef. This can be calculated by looking at
313 @code{clefPosition} and @code{clefGlyph}.")
314 (middleCOffset ,number? "The offset of
315 middle C from the position given by @code{middleCClefPosition} This
316 is used for ottava brackets.")
317 (middleCPosition ,number? "The place of the middle C, measured in
318 half staff-spaces. Usually determined by looking at
319 @code{middleCClefPosition} and @code{middleCOffset}.")
320 (midiInstrument ,string? "Name of the MIDI instrument to use.")
321 (midiMaximumVolume ,number? "Analogous to
322 @code{midiMinimumVolume}.")
323 (midiMinimumVolume ,number? "Set the minimum loudness for MIDI.
324 Ranges from 0 to@tie{}1.")
325 (minimumFret ,number? "The tablature auto string-selecting
326 mechanism selects the highest string with a fret at least
327 @code{minimumFret}.")
328 (minimumPageTurnLength ,ly:moment? "Minimum length of a rest for a
329 page turn to be allowed.")
330 (minimumRepeatLengthForPageTurn ,ly:moment? "Minimum length of a
331 repeated section for a page turn to be allowed within that section.")
334 (noChordSymbol ,markup? "Markup to be displayed for rests in a
335 ChordNames context.")
336 (noteToFretFunction ,procedure? "How to produce a fret diagram.
337 Parameters: A list of note events and a list of tabstring events.")
340 (ottavation ,markup? "If set, the text for an ottava spanner.
341 Changing this creates a new text spanner.")
342 (output ,ly:music-output? "The output produced by a score-level
343 translator during music interpretation.")
346 (pedalSostenutoStrings ,list? "See @code{pedalSustainStrings}.")
347 (pedalSostenutoStyle ,symbol? "See @code{pedalSustainStyle}.")
348 (pedalSustainStrings ,list? "A list of strings to print for
349 sustain-pedal. Format is @code{(@var{up} @var{updown} @var{down})},
350 where each of the three is the string to print when this is done with
352 (pedalSustainStyle ,symbol? "A symbol that indicates how to print
353 sustain pedals: @code{text}, @code{bracket} or @code{mixed} (both).")
354 (pedalUnaCordaStrings ,list? "See @code{pedalSustainStrings}.")
355 (pedalUnaCordaStyle ,symbol? "See @code{pedalSustainStyle}.")
356 (predefinedDiagramTable ,hash-table? "The hash table of predefined
357 fret diagrams to use in FretBoards.")
358 (printKeyCancellation ,boolean? "Print restoration alterations
359 before a key signature change.")
360 (printOctaveNames ,boolean? "Print octave marks for the
361 @code{NoteNames} context.")
362 (printPartCombineTexts ,boolean? "Set @q{Solo} and @q{A due} texts
363 in the part combiner?")
364 (proportionalNotationDuration ,ly:moment? "Global override for
365 shortest-playing duration. This is used for switching on proportional
369 (recordEventSequence ,procedure? "When
370 @code{Recording_group_engraver} is in this context, then upon
371 termination of the context, this function is called with current
372 context and a list of music objects. The list of contains entries with
373 start times, music objects and whether they are processed in this
375 (rehearsalMark ,integer? "The last rehearsal mark printed.")
376 (repeatCommands ,list? "This property is a list of commands
377 of the form @code{(list 'volta @var{x})}, where @var{x} is a string or
378 @code{#f}. @code{'end-repeat} is also accepted as a command.")
379 (repeatCountVisibility ,procedure? "A procedure taking as
380 arguments an integer and context, returning whether the corresponding
381 percent repeat number should be printed when @code{countPercentRepeats}
383 (restNumberThreshold ,number? "If a multimeasure rest has more
384 measures than this, a number is printed.")
387 (shapeNoteStyles ,vector? "Vector of symbols, listing style for
388 each note head relative to the tonic (qv.) of the scale.")
389 (shortInstrumentName ,markup? "See @code{instrument}.")
390 (shortVocalName ,markup? "Name of a vocal line, short version.")
391 (skipBars ,boolean? "If set to true, then skip the empty bars
392 that are produced by multimeasure notes and rests. These bars will
393 not appear on the printed output. If not set (the default),
394 multimeasure notes and rests expand into their full length, printing
395 the appropriate number of empty bars so that synchronization with other
401 \\set Score.skipBars= ##t
405 (skipTypesetting ,boolean? "If true, no typesetting is done,
406 speeding up the interpretation phase. Useful for debugging large
408 (soloIIText ,markup? "The text for the start of a solo for
409 voice @q{two} when part-combining.")
410 (soloText ,markup? "The text for the start of a solo when
412 (squashedPosition ,integer? "Vertical position of squashing for
413 @rinternals{Pitch_squash_engraver}.")
414 (staffLineLayoutFunction ,procedure? "Layout of staff lines,
415 @code{traditional}, or @code{semitone}.")
416 (stanza ,markup? "Stanza @q{number} to print before the start of a
417 verse. Use in @code{Lyrics} context.")
418 (stemLeftBeamCount ,integer? "Specify the number of beams to draw
419 on the left side of the next note. Overrides automatic beaming. The
420 value is only used once, and then it is erased.")
421 (stemRightBeamCount ,integer? "See @code{stemLeftBeamCount}.")
422 (stringNumberOrientations ,list? "See
423 @code{fingeringOrientations}.")
424 (stringOneTopmost ,boolean? "Whether the first string is
425 printed on the top line of the tablature.")
426 (stringTunings ,list? "The tablature strings tuning. It is a list
427 of the pitch (in semitones) of each string (starting with the lower
429 (strokeFingerOrientations ,list? "See
430 @code{fingeringOrientations}.")
431 (subdivideBeams ,boolean? "If set, multiple beams will be
432 subdivided at beat positions by only drawing one beam over the beat.")
433 (suggestAccidentals ,boolean? "If set, accidentals are typeset as
434 cautionary suggestions over the note.")
435 (systemStartDelimiter ,symbol? "Which grob to make for the start
436 of the system/staff? Set to @code{SystemStartBrace},
437 @code{SystemStartBracket} or @code{SystemStartBar}.")
438 (systemStartDelimiterHierarchy ,pair? "A nested list, indicating
439 the nesting of a start delimiters.")
442 (tablatureFormat ,procedure? "A function formatting a tablature
443 note head. Called with three arguments: string number, context and event.
444 It returns the text as a string.")
445 (tempoHideNote ,boolean? "Hide the note=count in tempo marks.")
446 (tempoText ,markup? "Text for tempo marks.")
447 (tempoUnitCount ,number? "Count for specifying tempo.")
448 (tempoUnitDuration ,ly:duration? "Unit for specifying tempo.")
449 (tempoWholesPerMinute ,ly:moment? "The tempo in whole notes per
451 (tieWaitForNote ,boolean? "If true, tied notes do not have to
452 follow each other directly. This can be used for writing out
454 (timeSignatureFraction ,number-pair? "A pair of numbers,
455 signifying the time signature. For example, @code{#'(4 . 4)} is a
456 4/4 time signature.")
457 (timing ,boolean? "Keep administration of measure length,
458 position, bar number, etc.? Switch off for cadenzas.")
459 (tonic ,ly:pitch? "The tonic of the current scale.")
460 (topLevelAlignment ,boolean? "If true, the @var{Vertical_align_engraver}
461 will create a @var{VerticalAlignment}; otherwise, it will create a
463 (trebleStaffProperties ,list? "An alist of property settings to
464 apply for the up staff of @code{PianoStaff}. Used by
465 @code{\\autochange}.")
466 (tremoloFlags ,integer? "The number of tremolo flags to add if no
467 number is specified.")
468 (tupletFullLength ,boolean? "If set, the tuplet is printed up to
469 the start of the next note.")
470 (tupletFullLengthNote ,boolean? "If set, end at the next note,
471 otherwise end on the matter (time signatures, etc.) before the note.")
472 (tupletSpannerDuration ,ly:moment? "Normally, a tuplet bracket is
473 as wide as the @code{\\times} expression that gave rise to it. By
474 setting this property, you can make brackets last shorter.
478 \\set tupletSpannerDuration = #(ly:make-moment 1 4)
479 \\times 2/3 @{ c8 c c c c c @}
484 (useBassFigureExtenders ,boolean? "Whether to use extender lines
485 for repeated bass figures.")
487 (verticallySpacedContexts ,list? "List of symbols, containing
488 context names whose vertical axis groups should be taken into account
489 for vertical spacing of systems.")
490 (vocalName ,markup? "Name of a vocal line.")
491 (voltaSpannerDuration ,ly:moment? "This specifies the maximum
492 duration to use for the brackets printed for @code{\\alternative}.
493 This can be used to shrink the length of brackets in the situation
494 where one alternative is very large.")
497 (whichBar ,string? "This property is read to determine what type
498 of bar line to create.
503 \\set Staff.whichBar = \"|:\"
507 This will create a start-repeat bar in this staff only. Valid values
508 are described in @rinternals{bar-line-interface}.")
512 (define-public all-internal-translation-properties
515 (set-object-property! (car x) 'internal-translation #t)
516 (apply translator-property-description x))
520 (associatedVoiceContext ,ly:context? "The context object of the
521 @code{Voice} that has the melody for this @code{Lyrics}.")
524 (barCheckLastFail ,ly:moment? "Where in the measure did the last
526 (beamMelismaBusy ,boolean? "Signal if a beam is present.")
527 (breakableSeparationItem ,ly:grob? "The breakable items in this
528 time step, for this staff.")
529 (busyGrobs ,list? "A queue of @code{(@var{end-moment} .
530 @var{GROB})} cons cells. This is for internal (C++) use only. This
531 property contains the grobs which are still busy (e.g. note heads,
535 (currentCommandColumn ,ly:grob? "Grob that is X-parent to all
536 current breakable (clef, key signature, etc.) items.")
537 (currentMusicalColumn ,ly:grob? "Grob that is X-parent to all
538 non-breakable items (note heads, lyrics, etc.).")
541 (dynamicAbsoluteVolumeFunction ,procedure? "A procedure that takes
542 one argument, the text value of a dynamic event, and returns the absolute
543 volume of that dynamic event.")
546 (finalizations ,list? "A list of expressions to evaluate before
547 proceeding to next time step. This is an internal variable.")
550 (graceSettings ,list? "Overrides for grace notes. This property
551 should be manipulated through the @code{add-grace-property} function.")
554 (hasStaffSpacing ,boolean? "True if the current
555 @code{CommandColumn} contains items that will affect spacing.")
558 (instrumentSupport ,grob-list? "A list of grobs to attach the
559 instrument name to.")
562 (lastKeySignature ,list? "Last key signature before a key
564 (localKeySignature ,list? "The key signature at this point in the
565 measure. The format is the same as for @code{keySignature}, but can
566 also contain @code{((@var{octave} . @var{name}) . (@var{alter}
567 @var{barnumber} . @var{measureposition}))} pairs.")
570 (melismaBusy ,boolean? "Signifies whether a melisma is active.
571 This can be used to signal melismas on top of those automatically
575 (originalMiddleCPosition ,integer? "Used for temporary overriding
576 middle@tie{}C in octavation brackets.")
579 (quotedEventTypes ,list? "A list of symbols, representing the
580 event types that should be duplicated for @code{\\quote} commands.")
581 ; (quotes ,hash-table? "A hash table, mapping names to
582 ;@code{music-event} vectors.")
585 (rootSystem ,ly:grob? "The System object.")
588 (scriptDefinitions ,list? "The description of scripts. This is
589 used by the @code{Script_engraver} for typesetting note-superscripts
590 and subscripts. See @file{scm/script.scm} for more information.")
591 (slurMelismaBusy ,boolean? "Signal if a slur is present.")
592 (stavesFound ,grob-list? "A list of all staff-symbols found.")
595 (tieMelismaBusy ,boolean? "Signal whether a tie is present.")
598 (define-public all-translation-properties
599 (append all-user-translation-properties
600 all-internal-translation-properties))
602 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
604 (define-public default-melisma-properties
605 '(melismaBusy slurMelismaBusy tieMelismaBusy beamMelismaBusy completionBusy))