1 ;;;; translator-property-description.scm -- part of backend documentation
3 ;;;; source file of the GNU LilyPond music typesetter
5 ;;;; (c) 1998--2004 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))
24 (define-public all-user-translation-properties
27 (apply translator-property-description x))
29 (aDueText ,string? "text for begin of a due")
30 (alignBassFigureAccidentals ,boolean?
31 "If true, then the accidentals are aligned in bass figure context.")
33 (allowBeamBreak ,boolean? "If true allow line breaks during beams.")
34 (associatedVoice ,string? "Name of the
35 Voice that has the melody for this Lyrics.")
36 (autoBeamSettings ,list? "Specifies
37 when automatically generated beams should begin and end.
38 See the notation manual for more information. ")
39 (autoAccidentals ,list? "List of
40 different ways to typeset an accidental. See the notation manual for more information on setting this.")
41 (autoBeaming ,boolean? "If set to true
42 then beams are generated automatically.")
44 (autoCautionaries ,list? "List similar to
45 autoAccidentals, but it controls cautionary accidentals rather than
46 normal ones. Both lists are tried, and the one giving the most accidentals
47 wins. In case of draw, a normal accidental is typeset.
49 (automaticBars ,boolean? " If set to true then bar lines will not be
50 printed automatically; they must be explicitly created with
51 @code{\\bar} command. Unlike the @code{\\cadenza} keyword, measures
52 are still counted. Bar generation will resume according to that count
53 if this property is unset.
56 (barAlways ,boolean? "If set to true a bar line is drawn after each
59 (barCheckSynchronize ,boolean? "If true then reset measurePosition
60 when finding a barcheck.")
62 (barNumberVisibility ,procedure? "Procedure that takes an int and
63 returns whether the corresponding bar number should be printed")
64 (bassFigureFormatFunction ,procedure? "DOCME")
65 (beatLength ,ly:moment? "The length of one beat in this time signature.")
67 "List of beatgroups. Eg. in 5/8 time #(list 2 3).")
70 (breakAlignOrder ,list? "Defines the order in which
71 prefatory matter (clefs, key signatures) appears, eg. this puts the
72 key signatures after the bar lines:
75 \\property Score.breakAlignOrder = #'(
86 (centralCPosition ,number? "Place of the central C, measured in half
87 staffspaces. Usually determined by looking at clefPosition and
90 (chordNameFunction ,procedure?
91 "The function that converts lists of pitches to chord names.")
92 (chordNoteNamer ,procedure?
93 "Function that converts from a pitch object to a text markup. Used for single pitches.")
94 (chordRootNamer ,procedure?
95 "Function that converts from a pitch object to a text markup. Used for chords.")
96 (chordNameExceptions ,list?
97 "Alist of chord exceptions. Contains (CHORD . MARKUP) entries.")
98 (chordNameExceptionsFull ,list?
99 "Alist of chord exceptions. Contains (CHORD . (MARKUP)) entries.")
100 (chordNameExceptionsPartial ,list?
101 "Alist of partial chord exceptions. Contains (CHORD . (PREFIX-MARKUP SUFFIX-MARKUP)) entries.")
102 (chordNameSeparator ,markup?
103 "The markup object used to separate parts of a chord name.")
105 (chordChanges ,boolean? "Only show changes in chords scheme?")
106 (clefGlyph ,string? "Name of the symbol within the music font")
107 (clefOctavation ,integer? "Add
108 this much extra octavation. Values of 7 and -7 are common.")
110 (clefPosition ,number? "Where should the center of the clef symbol go?
111 The unit of this distance is the half staff space, and 0 represents the vertical center.")
113 (connectArpeggios ,boolean? " If set, connect all arpeggios that are
114 found. In this way, you can make arpeggios that cross staves. ")
115 (createKeyOnClefChange ,boolean? "Print a key signature whenever the clef is changed.")
116 (crescendoText ,markup? "Text to print at start of non-hairpin crecscendo, ie: @samp{cresc.}")
117 (crescendoSpanner ,symbol? "Type of spanner to be used for crescendi.
118 One of: @samp{hairpin}, @samp{line}, @samp{dashed-line},
119 @samp{dotted-line}. If unset, hairpin type is used.")
120 (decrescendoText ,markup? "Text to print at start of non-hairpin decrecscendo, ie: @samp{dim.}")
122 (drumPitchTable ,hash-table? "A table mapping percussion
123 instruments (symbols) to pitches.")
125 (drumStyleTable ,hash-table? "A hash table containing mapping
126 drums to layout settings. Predefined values: @code{drums-style},
127 @code{timbales-style}, @code{congas-style}, @code{bongos-style} and
128 @code{percussion-style}.
130 The layout style is a hash table, containing the drum-pitches (eg. the
131 symbol @code{hihat}) as key, and a list (@var{notehead-style}
132 @var{script} @var{vertical-position}) as values.
134 (currentBarNumber ,integer? "Contains the current barnumber. This property is incremented at
137 (defaultBarType ,string? "Sets the default type of bar line.
138 Available bar types: [FIXME];
140 This variable is typically read by Timing_engraver at Score level, so
141 overriding Staff.defaultBarType will have no effect.
144 (decrescendoSpanner ,symbol? "Type of spanner to be used for
145 decrescendi. One of: @samp{hairpin}, @samp{line}, @samp{dashed-line},
146 @samp{dotted-line}. If unset, hairpin type is used.")
148 (explicitClefVisibility ,procedure? "break-visibility function for clef changes.")
150 (explicitKeySignatureVisibility ,procedure? "break-visibility
151 function for explicit Key changes; \\override of #'break-visibility
152 will set the visibility for normal (ie. at the start of the line) key
155 (extraNatural ,boolean? "Whether to typeset an
156 extra natural sign before accidentals changing from a non-natural to
157 another non-natural.")
159 (extraVerticalExtent ,number-pair?
160 "extra vertical extent, same format as MinimumVerticalExtent")
163 (followVoice ,boolean? "if set, note heads are tracked across staff
164 switches by a thin line")
167 "The relative size of all grobs in a context. This is
168 done using the @code{Font_size_engraver}.")
170 (fingeringOrientations ,list?
171 "List of symbols, containing left, right, up and/or down. This list
172 determines where fingerings are put relative to the chord being
175 (forceClef ,boolean? "Show clef symbol, even if it hasn't
176 changed. Only active for the first clef after the property is set, not
177 for the full staff.")
179 (highStringOne ,boolean? "Whether the 1st string is the string with
180 highest pitch on the instrument. This used by the automatic string
181 selector for tab notation.")
183 (ignoreMelismata ,boolean? "Ignore melismata for this @internalsref{Lyrics}.")
184 (instr ,markup? "see @code{instrument}")
186 (instrument ,markup? "The name to print left of a staff. The
187 @code{instrument} property labels the staff in the first system, and
188 the @code{instr} property labels following lines.")
189 (instrumentEqualizer ,procedure? "[DOCUMENT-ME]")
190 (instrumentTransposition ,ly:pitch? "Define the transposition of the instrument. This is used to transpose the MIDI output, and @code{\\quote}s.")
192 (instrumentSupport ,list? "list of grobs to attach instrument name
194 (keyAccidentalOrder ,list? "
195 Alist that defines in what order alterations should be printed.
196 The format is (NAME . ALTER), where NAME is from 0 .. 6 and ALTER from -1, 1.
199 (keySignature ,list? "The current key signature. This is an alist
200 containing (NAME . ALTER) or ((OCTAVE . NAME) . ALTER).
201 where NAME is from 0.. 6 and
202 ALTER from -4 (double flat) to 4 (double sharp).
205 (majorSevenSymbol ,markup? "How should
206 the major7 be formatted in a chord name?")
207 (markFormatter ,procedure? "Procedure
208 taking as arguments context and rehearsal mark. It should return the
209 formatted mark as a markup object.")
211 (measureLength ,ly:moment? "Length of one
212 measure in the current time signature last?")
214 (measurePosition ,ly:moment? "How much of the current measure
215 have we had. This can be set manually to create incomplete
218 (melismaBusyProperties ,list? "List of properties (symbols) to
219 determine whether a melisma is playing. Setting this property will
220 influence how lyrics are aligned to notes. For example, if set to
221 @code{#'(melismaBusy beamMelismaBusy)}, only manual melismata and
222 manual beams are considered. Possible values include
223 @code{melismaBusy}, @code{slurMelismaBusy}, @code{tieMelismaBusy}, and
224 @code{beamMelismaBusy}")
227 (metronomeMarkFormatter ,procedure? "How to produce a metronome
228 markup. Called with 2 arguments, event and context.")
229 (midiInstrument ,string? "Name of the MIDI instrument to use ")
230 (midiMinimumVolume ,number? "[DOCUMENT-ME]")
231 (midiMaximumVolume ,number? "[DOCUMENT-ME]")
232 (minimumFret ,number? "The tablature auto string-selecting mechanism
233 selects the highest string with a fret not less than minimumFret")
234 (minimumVerticalExtent ,number-pair? "minimum vertical extent, same
235 format as VerticalExtent")
236 (recordEventSequence ,procedure? "Upon termination of this context,
237 this function is called with current context and a list of music
238 objects. The list of contains entries with start times, music objects
239 and whether they're processed in this context.")
240 (ottavation ,string? "If set, the text for an 8va spanner. Changing
241 this implies a new text spanner. ")
242 (pedalSustainStrings ,list? "List of string to print for
243 sustain-pedal. Format is (UP UPDOWN DOWN), where each of the three is
244 the string to print when this is done with the pedal.")
245 (pedalUnaCordaStrings ,list? "see pedalSustainStrings.")
246 (pedalSostenutoStrings ,list? "see pedalSustainStrings.")
247 (pedalSustainStyle ,symbol? "A symbol that indicates how to print
248 sustain pedals: text, bracket or mixed (both).")
249 (pedalUnaCordaStyle ,symbol? "see pedalSustainStyle.")
250 (pedalSostenutoStyle ,symbol? "see pedalSustainStyle.")
251 (printOctaveNames ,boolean? "Print octave marks for the NoteNames context.")
252 (rehearsalMark ,integer? "The last rehearsal mark printed.")
253 (repeatCommands ,list? "This property is read to find any command of the form (volta . X), where X is a string or #f")
255 (restNumberThreshold ,number?
256 "If a multimeasure rest takes less
257 than this number of measures, no number is printed. ")
259 (skipBars ,boolean? "If set to true, then
260 skip the empty bars that are produced by multimeasure notes and rests.
261 These bars will not appear on the printed output. If not set (the
262 default) multimeasure notes and rests expand into their full length,
263 printing the appropriate number of empty bars so that synchronization
264 with other voices is preserved.
268 @@lilypond[fragment,verbatim,center]
269 r1 r1*3 R1*3 \\\\property Score.skipBars= ##t r1*3 R1*3
273 (skipTypesetting ,boolean?
274 "When true, all no typesetting is done at this
275 moment, causing the interpretation phase to go a lot faster. This can
276 help with debugging large scores.")
277 (soloADue ,boolean? "set Solo/A due texts in the part combiner?")
278 (soloIIText ,string? "text for begin of solo for voice ``two'' when part-combining.")
279 (soloText ,string? "text for begin of solo when part-combining.")
280 (sparseTies ,boolean? "only create one tie per chord.")
281 (squashedPosition ,integer? " Vertical position of
282 squashing for Pitch_squash_engraver.")
284 (stringOneTopmost ,boolean? "Whether the 1st string is printed on the
285 top line of the tablature.")
287 (stanza ,markup? "Stanza `number' to print before the start of a
288 verse. Use in Lyrics context.")
290 (stemLeftBeamCount ,integer? " Specify the number of beams to draw on
291 the left side of the next note. Overrides automatic beaming. The
292 value is only used once, and then it is erased. [JUNKME.]")
294 (stemRightBeamCount ,integer? "idem, for the right side. [JUNKME]")
296 (stringTunings ,list? "The tablature strings tuning. Must be a list of
297 the different semitons pitch of each string (starting by the lower
300 (subdivideBeams ,boolean? "If set, multiple beams will be subdivided
301 at beat positions - by only drawing one beam over the beat.")
303 (systemStartDelimiter ,symbol? "Which grob to make for the start of
304 the system/staff? Set to @code{SystemStartBrace},
305 @code{SystemStartBracket} or @code{SystemStartBar}.")
307 (tablatureFormat ,procedure? "Function formatting a tab notehead; it
308 takes a string number, a list of string tunings and Pitch object. It
309 returns the text as a string.")
311 (timeSignatureFraction ,number-pair?
312 "pair of numbers, signifying the time signature. For example #'(4 . 4)
313 is a 4/4 time signature.")
315 (timing ,boolean? " Keep administration of measure length, position, bar number, etc?
316 Switch off for cadenzas.")
318 "The tonic of the current scale")
320 (tremoloFlags ,integer? "Number of tremolo flags to add if none is specified.")
322 (tupletNumberFormatFunction
324 "Function taking a music as input, producing a string. This function
325 is called to determine the text to print on a tuplet bracket.")
327 (tupletSpannerDuration ,ly:moment? "
328 Normally a tuplet bracket is as wide as the
329 @code{\\times} expression that gave rise to it. By setting this
330 property, you can make brackets last shorter. Example
333 @@lilypond[verbatim,fragment]
334 context Voice \\times 2/3 @{
335 property Voice.tupletSpannerDuration = #(ly:make-moment 1 4)
341 (verticalAlignmentChildCallback ,procedure? "what callback to add to children of a vertical alignment.
342 It determines what alignment procedure is used on the alignment
344 (verticalExtent ,number-pair? "hard coded vertical extent. The format
345 is a pair of dimensions, for example, this sets the sizes of a staff
346 to 10 (5+5) staffspaces high.
349 property Staff.verticalExtent = #'(-5.0 . 5.0)
353 This does not work for Voice or any other context that doesn't form a
356 (vocalName ,markup? "Name of a vocal line.")
357 (vocNam ,markup? "Name of a vocal line, short version.")
359 (voltaOnThisStaff ,boolean?
360 "Normally, volta brackets are put only on the topmost staff. Setting
361 this variable to true, will force a bracket to be on this staff as
364 (voltaSpannerDuration ,ly:moment? "This specifies the maximum duration
365 to use for the brackets printed for @code{\\alternative}. This can be
366 used to shrink the length of brackets in the situation where one
367 alternative is very large.")
371 "This property is read to determine what type of barline to create.
375 \\property Staff.whichBar = \"|:\"
378 This will create a start-repeat bar in this staff only.
379 Valid values are described in @internalsref{bar-line-interface}.
383 (define-public all-internal-translation-properties
386 (set-object-property! (car x) 'internal-translation #t)
387 (apply translator-property-description x)
391 `((slurMelismaBusy ,boolean? "Signal if a slur is present.")
392 (originalCentralCPosition
394 "Used for temporary overriding central C in octavation brackets. ")
395 (melismaBusy ,boolean? "Signifies
396 whether a melisma is active. This can be used to signal melismas on
397 top of those automatically detected. ")
398 (graceSettings ,vector?
399 "Overrides for grace notes. This property should
400 be manipulated through the @code{add-grace-property} function.")
401 (currentCommandColumn ,ly:grob? "Grob that is X-parent to all
402 current breakable (clef, key signature, etc.) items.")
403 (currentMusicalColumn ,ly:grob? "Grob that is X-parent to all
404 non-breakable items (note heads, lyrics, etc.).")
405 (breakableSeparationItem ,ly:grob?
406 "The breakable items in this time step,
409 (localKeySignature ,list? "the key signature at this point in the
410 measure. The format is the same as for keySignature, but can also
411 contain ((@var{octave} . @var{name}) . (@var{alter} . @var{barnumber}))
412 pairs. It is reset at every bar line." )
415 (localKeySignatureChanges ,list? "Experimental. [DOCME]")
417 (finalizations ,list? "List of expressions to evaluate before proceeding to next time step. Internal variable.")
418 (busyGrobs ,list? "a queue of (@var{end-moment} . @var{GROB})
419 conses. This is for internal (C++) use only. This property contains
420 the grobs which are still busy (eg. noteheads, spanners, etc.)
422 (barCheckLastFail ,ly:moment? "Where in the measurze did the last barcheck fail?")
423 (associatedVoiceContext ,ly:context? "The context object of the Voice that has the melody for this Lyrics.")
424 (acceptHashTable ,vector? "Internal
425 variable: store table with MusicName to Engraver entries.")
426 (acknowledgeHashTable ,vector?
427 "Internal variable: store interface to engraver smob table for current
430 (beamMelismaBusy ,boolean? "Signal if a beam is present.")
431 (dynamicAbsoluteVolumeFunction ,procedure? "[DOCUMENT-ME]")
433 (lastKeySignature ,list? "Last key signature before a key
436 (scriptDefinitions ,list? "Description of scripts. This is used by
437 Script_engraver for typesetting note-super/subscripts. See
438 @file{scm/script.scm} for more information
440 (quotes ,hash-table? "Hash table, mapping names to music-event vectors.")
441 (stavesFound ,grob-list? "list of all staff-symbols found.")
442 (tieMelismaBusy ,boolean? "Signal whether a tie is present.")
446 (define-public all-translation-properties
447 (append all-user-translation-properties
448 all-internal-translation-properties))
450 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
452 (define-public default-melisma-properties '(melismaBusy slurMelismaBusy tieMelismaBusy beamMelismaBusy))