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. See the notation manual for more information on setting this.")
  41      (autoBeaming ,boolean? "If set to true
  42 then beams are generated automatically.")
  43
  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.
  48 ")
  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.
  54 ")
  55
  56      (barAlways ,boolean? "If set to true a bar line is drawn after each
  57 note.")
  58
  59      (barCheckSynchronize ,boolean? "If true then reset measurePosition
  60 when finding a barcheck.")
  61
  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.")
  66      (beatGrouping ,list?
  67                    "List of beatgroups. Eg. in 5/8 time #(list 2 3).")
  68
  69
  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:
  73
  74 @example
  75         \\property Score.breakAlignOrder = #'(
  76           span-bar
  77           breathing-sign
  78           clef
  79           staff-bar
  80           key
  81           time-signature
  82         )
  83 @end example
  84 ")
  85
  86      (centralCPosition ,number? "Place of the central C, measured in half
  87 staffspaces.  Usually determined by looking at clefPosition and
  88 clefGlyph.")
  89
  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.")
 104
 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.")
 109
 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.")
 112
 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.}")
 121
 122      (drumPitchTable ,hash-table? "A table mapping percussion
 123 instruments (symbols) to pitches.")
 124
 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}.
 129
 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.
 133  ")
 134      (currentBarNumber ,integer? "Contains the current barnumber. This property is incremented at
 135 every barline.
 136 ")
 137      (defaultBarType ,string? "Sets the default type of bar line.
 138 Available bar types: [FIXME];
 139
 140 This variable is typically read by Timing_engraver at Score level, so
 141 overriding Staff.defaultBarType will have no effect.
 142 ")
 143
 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.")
 147
 148      (explicitClefVisibility ,procedure? "break-visibility function for clef changes.")
 149
 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
 153 signatures.")
 154
 155      (extraNatural ,boolean? "Whether to typeset an
 156 extra natural sign before accidentals changing from a non-natural to
 157 another non-natural.")
 158
 159      (extraVerticalExtent ,number-pair?
 160                           "extra vertical extent, same format as MinimumVerticalExtent")
 161
 162
 163      (followVoice ,boolean? "if set, note heads are tracked across staff
 164 switches by a thin line")
 165
 166      (fontSize ,number?
 167                "The relative size of all grobs in a context. This is
 168 done using the @code{Font_size_engraver}.")
 169
 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
 173 fingered.")
 174
 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.")
 178
 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.")
 182
 183      (ignoreMelismata ,boolean? "Ignore melismata for this @internalsref{Lyrics}.")
 184      (instr ,markup? "see @code{instrument}")
 185
 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
 191      (instrumentSupport ,list? "list of grobs to attach instrument name
 192 to.")
 193      (keyAccidentalOrder ,list? "
 194 Alist that defines in what order  alterations should be printed.
 195 The format is (NAME . ALTER), where NAME is from 0 .. 6 and ALTER from  -1, 1.
 196 ")
 197
 198      (keySignature ,list? "The current key signature. This is an alist
 199 containing (NAME . ALTER) or ((OCTAVE . NAME) . ALTER).
 200  where NAME is from 0.. 6 and
 201 ALTER from -4 (double flat) to 4 (double sharp).
 202 ")
 203
 204      (majorSevenSymbol ,markup? "How should
 205 the major7 be formatted in a chord name?")
 206      (markFormatter ,procedure? "Procedure
 207 taking as arguments context and rehearsal mark. It should return the
 208 formatted mark as a markup object.")
 209
 210      (measureLength ,ly:moment? "Length of one
 211 measure in the current time signature last?")
 212
 213      (measurePosition ,ly:moment? "How much of the current measure
 214 have we had.  This can be set manually to create incomplete
 215 measures.")
 216
 217      (melismaBusyProperties ,list? "List of properties (symbols) to
 218 determine whether a melisma is playing.  Setting this property will
 219 influence how lyrics are aligned to notes.  For example, if set to
 220 @code{#'(melismaBusy beamMelismaBusy)}, only manual melismata and
 221 manual beams are considered. Possible values include
 222 @code{melismaBusy}, @code{slurMelismaBusy}, @code{tieMelismaBusy}, and
 223 @code{beamMelismaBusy}")
 224
 225
 226      (metronomeMarkFormatter ,procedure? "How to produce a metronome
 227 markup.  Called with 2 arguments, event and context.")
 228      (midiInstrument ,string? "Name of the MIDI instrument to use ")
 229      (midiMinimumVolume ,number? "[DOCUMENT-ME]")
 230      (midiMaximumVolume ,number? "[DOCUMENT-ME]")
 231      (minimumFret ,number? "The tablature auto string-selecting mechanism
 232 selects the highest string with a fret not less than minimumFret")
 233      (minimumVerticalExtent ,number-pair? "minimum vertical extent, same
 234 format as VerticalExtent")
 235      (recordEventSequence ,procedure? "Upon termination of this context,
 236 this function is called with current context and a list of music
 237 objects.  The list of contains entries with start times, music objects
 238 and whether they're processed in this context.")
 239      (ottavation ,string? "If set, the text for an 8va spanner. Changing
 240 this implies a new text spanner. ")
 241      (pedalSustainStrings ,list? "List of string to print for
 242 sustain-pedal. Format is (UP UPDOWN DOWN), where each of the three is
 243 the string to print when this is done with the pedal.")
 244      (pedalUnaCordaStrings ,list? "see pedalSustainStrings.")
 245      (pedalSostenutoStrings ,list? "see pedalSustainStrings.")
 246      (pedalSustainStyle ,symbol? "A symbol that indicates how to print
 247 sustain pedals: text, bracket or mixed (both).")
 248      (pedalUnaCordaStyle ,symbol? "see pedalSustainStyle.")
 249      (pedalSostenutoStyle ,symbol? "see pedalSustainStyle.")
 250      (printOctaveNames ,boolean? "Print octave marks for the NoteNames context.")
 251      (rehearsalMark ,integer? "The last rehearsal mark printed.")
 252      (repeatCommands ,list? "This property is read to find any command of the form (volta . X), where X is a string or #f")
 253
 254      (restNumberThreshold ,number?
 255                           "If a multimeasure rest takes less
 256 than this number of measures, no number is printed. ")
 257
 258      (skipBars ,boolean? "If set to true, then
 259 skip the empty bars that are produced by multimeasure notes and rests.
 260 These bars will not appear on the printed output.  If not set (the
 261 default) multimeasure notes and rests expand into their full length,
 262 printing the appropriate number of empty bars so that synchronization
 263 with other voices is preserved.
 264
 265
 266 @example
 267 @@lilypond[fragment,verbatim,center]
 268 r1 r1*3 R1*3  \\\\property Score.skipBars= ##t r1*3 R1*3
 269 @@end lilypond
 270 @end example
 271 ")
 272      (skipTypesetting ,boolean?
 273                       "When true, all no typesetting is done at this
 274 moment, causing the interpretation phase to go a lot faster. This can
 275 help with debugging large scores.")
 276      (soloADue ,boolean? "set Solo/A due texts in the part combiner?")
 277      (soloIIText ,string? "text for begin of solo for voice ``two'' when part-combining.")
 278      (soloText ,string? "text for begin of solo when part-combining.")
 279      (sparseTies ,boolean? "only create one tie per chord.")
 280      (squashedPosition ,integer? " Vertical position of
 281 squashing for Pitch_squash_engraver.")
 282
 283      (stringOneTopmost ,boolean? "Whether the 1st string is printed on the
 284 top line of the tablature.")
 285
 286      (stanza ,markup? "Stanza `number' to print before the start of a
 287 verse. Use in Lyrics context.")
 288
 289      (stemLeftBeamCount ,integer? " Specify the number of beams to draw on
 290 the left side of the next note.  Overrides automatic beaming.  The
 291 value is only used once, and then it is erased. [JUNKME.]")
 292
 293      (stemRightBeamCount ,integer? "idem, for the right side. [JUNKME]")
 294
 295      (stringTunings ,list? "The tablature strings tuning. Must be a list of
 296 the different semitons pitch of each string (starting by the lower
 297 one).")
 298
 299      (subdivideBeams ,boolean? "If set, multiple beams will be subdivided
 300 at beat positions - by only drawing one beam over the beat.")
 301
 302      (systemStartDelimiter ,symbol? "Which grob to make for the start of
 303 the system/staff? Set to @code{SystemStartBrace},
 304 @code{SystemStartBracket} or @code{SystemStartBar}.")
 305
 306      (tablatureFormat ,procedure? "Function formatting a tab notehead; it
 307 takes a string number, a list of string tunings and Pitch object. It
 308 returns the text as a string.")
 309
 310      (timeSignatureFraction ,number-pair?
 311                             "pair of numbers, signifying the time signature. For example #'(4 . 4)
 312 is a 4/4 time signature.")
 313
 314      (timing ,boolean? " Keep administration of measure length, position, bar number, etc?
 315 Switch off for cadenzas.")
 316      (tonic ,ly:pitch?
 317             "The tonic of the current scale")
 318      (transposing ,integer? "Transpose the MIDI output.  Set this property to the number of half-steps to transpose by.")
 319
 320      (tremoloFlags ,integer? "Number of tremolo flags to add if none is specified.")
 321
 322      (tupletNumberFormatFunction
 323       ,procedure?
 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.")
 326
 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
 331
 332 @example
 333 @@lilypond[verbatim,fragment]
 334 context Voice \\times 2/3 @{
 335   property Voice.tupletSpannerDuration = #(ly:make-moment 1 4)
 336   c-[8 c c-] c-[ c c-]
 337 @}
 338 @@end lilypond
 339 @end example
 340 .")
 341      (verticalAlignmentChildCallback ,procedure? "what callback to add to children of a vertical alignment.
 342 It determines what alignment procedure is used on the alignment
 343 itself.  .")
 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.
 347
 348 @example
 349 property Staff.verticalExtent = #'(-5.0 . 5.0)
 350 @end example
 351
 352
 353 This does not work for Voice or any other context  that doesn't form a
 354 vertical group.")
 355
 356      (vocalName ,markup? "Name of a vocal line.")
 357      (vocNam ,markup? "Name of a vocal line, short version.")
 358
 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
 362 well.")
 363
 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.")
 368
 369      (whichBar
 370       ,string?
 371       "This property is read to determine what type of barline to create.
 372
 373 Example:
 374 @example
 375 \\property Staff.whichBar = \"|:\"
 376 @end example
 377
 378 This will create a start-repeat bar in this staff only.
 379 Valid values are described in @internalsref{bar-line-interface}.
 380 ")
 381      )))
 382
 383 (define-public all-internal-translation-properties
 384   (map
 385    (lambda (x)
 386      (set-object-property! (car x) 'internal-translation #t)
 387      (apply translator-property-description x)
 388
 389      )
 390
 391    `((slurMelismaBusy ,boolean? "Signal if a slur is present.")
 392      (originalCentralCPosition
 393       ,integer?
 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,
 407 for this staff.")
 408
 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."  )
 413
 414
 415      (localKeySignatureChanges ,list? "Experimental. [DOCME]")
 416
 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.)
 421 ")
 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
 428 context.")
 429
 430      (beamMelismaBusy ,boolean? "Signal if a beam is present.")
 431      (dynamicAbsoluteVolumeFunction ,procedure? "[DOCUMENT-ME]")
 432
 433      (lastKeySignature ,list? "Last key signature before a key
 434 signature change.")
 435
 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
 439 ")
 440      (stavesFound ,grob-list? "list of all staff-symbols found.")
 441      (tieMelismaBusy ,boolean? "Signal whether a tie is present.")
 442      )
 443    ))
 444
 445 (define-public all-translation-properties
 446   (append all-user-translation-properties
 447           all-internal-translation-properties))
 448
 449 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 450
 451 (define-public default-melisma-properties '(melismaBusy slurMelismaBusy tieMelismaBusy beamMelismaBusy))