scm/define-context-properties.scm

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