scm/translator-description.scm

   1
   2 (define (engraver-description name description created-elts properties)
   3   (list name description created-elts properties)
   4   )
   5
   6
   7 (define engraver-description-alist
   8   (list
   9    (cons
  10     'Stem_engraver
  11     (engraver-description
  12      "Stem_engraver"
  13      "Create stems and single-stem tremolos.  It also works together with
  14 the beam engraver for overriding beaming."
  15      '(Stem StemTremolo)
  16      '(tremoloFlags
  17       stemLeftBeamCount
  18       stemRightBeamCount
  19       )))
  20
  21    (cons
  22     'Hyphen_engraver
  23     (engraver-description
  24      "Hyphen_engraver"
  25      "Create lyric hyphens"
  26      '(LyricHyphen)
  27      '(
  28       )))
  29
  30    (cons
  31     'Extender_engraver
  32     (engraver-description
  33      "Extender_engraver"
  34      "Create lyric extenders"
  35      '(LyricExtender)
  36      '(
  37       )))
  38
  39
  40    (cons
  41     'Separating_line_group_engraver
  42     (engraver-description
  43      "Separating_line_group_engraver"
  44      "Generates objects for computing spacing parameters."
  45      '(SeparationItem SeparatingGroupSpanner)
  46      '(
  47       )))
  48
  49    (cons
  50     'Axis_group_engraver
  51     (engraver-description
  52      "Axis_group_engraver"
  53      "Group all objects created in this context in a VerticalAxisGroup spanner."
  54      '(VerticalAxisGroup)
  55      '(VerticalExtent MinimumVerticalExtent ExtraVerticalExtent)
  56      ))
  57
  58    (cons
  59     'Hara_kiri_engraver
  60     (engraver-description
  61      "Hara_kiri_engraver"
  62      "Like Axis_group_engraver, but make a hara kiri spanner, and add
  63 interesting items (ie. note heads, lyric syllables and normal rests)"
  64      '(HaraKiriVerticalGroup)
  65      '()
  66      ))
  67
  68
  69    (cons
  70     'Local_key_engraver
  71     (engraver-description
  72      "Local_key_engraver"
  73      "Make accidentals.  Catches note heads, ties and notices key-change
  74    events.  Due to interaction with ties (which don't come together
  75    with note heads), this needs to be in a context higher than Tie_engraver.
  76    (FIXME)."
  77      '(Accidentals)
  78      '(
  79       localKeySignature
  80       forgetAccidentals
  81       noResetKey
  82
  83       )))
  84
  85
  86    (cons
  87     'Volta_engraver
  88     (engraver-description
  89      "Volta_engraver"
  90      "Make volta brackets"
  91      '(VoltaBracket)
  92      '(repeatCommands voltaSpannerDuration)
  93      ))
  94
  95    (cons
  96     'Clef_engraver
  97     (engraver-description
  98      "Clef_engraver"
  99      "Determine and set reference point for pitches"
 100      '(Clef OctavateEight)
 101      '(
 102       clefPosition
 103       clefGlyph
 104       centralCPosition
 105       clefOctavation
 106       explicitClefVisibility
 107       clefPitches
 108
 109       )))
 110
 111    (cons
 112     'A2_engraver
 113     (engraver-description
 114      "A2_engraver"
 115      "Part combine engraver for orchestral scores.
 116
 117 The markings @emph{a2}, @emph{Solo} and @emph{Solo II}, are
 118 created by this engraver.  It also acts upon instructions of the part
 119 combiner.  Another thing that the this engraver, is forcing of stem,
 120 slur and tie directions, always when both threads are not identical;
 121 up for the musicexpr called @code{one}, down for the musicexpr called
 122 @code{two}.
 123
 124 "
 125      '(TextScript)
 126      '(
 127       combineParts
 128       noDirection
 129       soloADue
 130       soloText
 131       soloIIText
 132       aDueText
 133       split-interval
 134       unison
 135       solo
 136       unisilence
 137       unirhythm
 138       )))
 139
 140    (cons
 141     'Align_note_column_engraver
 142     (engraver-description
 143      "Align_note_column_engraver"
 144      "Generate object to put grace notes from left to right."
 145      '(GraceAlignment)
 146      '(
 147
 148       graceAlignPosition
 149       graceAccidentalSpace
 150       )))
 151
 152    (cons
 153     'Arpeggio_engraver
 154     (engraver-description
 155      "Arpeggio_engraver"
 156      "Generate an Arpeggio from a Arpeggio_req"
 157      '(Arpeggio)
 158      '(
 159       )))
 160
 161    (cons
 162    'Auto_beam_engraver
 163     (engraver-description
 164      "Auto_beam_engraver"
 165      "Generate beams based on measure characteristics and observed
 166 Stems.  Uses beatLength, measureLength and measurePosition to decide
 167 when to start and stop a beam.  Overriding beaming is done through
 168 @ref{Stem_engraver} properties stemLeftBeamCount and
 169 stemRightBeamCount.
 170 "
 171      '(
 172        Beam)
 173      '(
 174       noAutoBeaming
 175       autoBeamSettings)))
 176
 177    (cons
 178     'Bar_engraver
 179     (engraver-description
 180      "Bar_engraver"
 181      "Create barlines. This engraver is controlled through the
 182 @code{whichBar} property. If it has no bar line to create, it will forbid a linebreak at this point"
 183      '(BarLine)
 184      '(
 185       whichBar
 186       staffsFound
 187       )))
 188
 189
 190    (cons
 191     'Bar_number_engraver
 192     (engraver-description
 193      "Bar_number_engraver"
 194      "A bar number is created whenever measurePosition is zero. It is
 195 put on top of all staffs, and appears only at  left side of the staff."
 196      '(BarNumber)
 197      '(
 198       currentBarNumber
 199       )))
 200
 201
 202    (cons
 203     'Beam_engraver
 204     (engraver-description
 205      "Beam_engraver"
 206      "Handles Beam_requests by engraving Beams.    If omitted, then notes will be
 207     printed with flags instead of beams."
 208      '(Beam)
 209      '(
 210       beamMelismaBusy
 211       )))
 212
 213    (cons
 214     'Break_align_engraver
 215     (engraver-description
 216      "Break_align_engraver"
 217      "Align grobs with corresponding break-align-symbols into groups, and order the groups according to breakAlignOrder"
 218      '(BreakAlignment BreakAlignGroup LeftEdge)
 219      '(
 220       breakAlignOrder
 221
 222       )))
 223
 224
 225    (cons
 226     'Breathing_sign_engraver
 227     (engraver-description
 228      "Breathing_sign_engraver"
 229      ""
 230      '(BreathingSign)
 231      '(
 232       )))
 233
 234
 235    (cons
 236     'Chord_name_engraver
 237     (engraver-description
 238      "Chord_name_engraver"
 239      "Catch Note_req's, Tonic_reqs, Inversion_reqs, Bass_req
 240 and generate the appropriate chordname."
 241      '(ChordName)
 242      '(chordChanges)))
 243
 244
 245    (cons
 246     'Chord_tremolo_engraver
 247     (engraver-description
 248      "Chord_tremolo_engraver"
 249      "Generates beams for the \repeat X tremolo ... construct"
 250      '(Beam)
 251      '(
 252       )))
 253
 254
 255
 256    (cons
 257     'Collision_engraver
 258     (engraver-description
 259      "Collision_engraver"
 260      ""
 261      '(NoteCollision
 262        )
 263      '(
 264       )))
 265
 266    (cons
 267     'Custos_engraver
 268     (engraver-description
 269      "Custos_engraver"
 270      ""
 271      '(Custos)
 272      '(
 273       )))
 274
 275
 276    (cons
 277     'Dot_column_engraver
 278     (engraver-description
 279      "Dot_column_engraver"
 280      " Engraves dots on dotted notes shifted to the right of the note.
 281 If omitted, then dots appear on top of the notes.
 282 "
 283      '(DotColumn
 284        )
 285      '(
 286       )))
 287
 288
 289    (cons
 290     'Dynamic_engraver
 291     (engraver-description
 292      "Dynamic_engraver"
 293      ""
 294      '(DynamicLineSpanner
 295        DynamicText Hairpin
 296        TextSpanner)
 297      '(
 298       )))
 299
 300
 301
 302
 303    (cons
 304     'Grace_position_engraver
 305     (engraver-description
 306      "Grace_position_engraver"
 307      "Attach a grace note alignment to a note-column "
 308      '()
 309      '(
 310       )))
 311
 312    (cons
 313     'Grace_engraver_group
 314     (engraver-description
 315      "Grace_engraver_group"
 316      "An engraver that creates a `shielded' context-tree with separate notion of time"
 317      '()
 318      '(
 319       )))
 320
 321
 322    (cons
 323     'Instrument_name_engraver
 324     (engraver-description
 325      "Instrument_name_engraver"
 326      " Prints the name of the instrument (specified by
 327     @code{Staff.instrument} and @code{Staff.instr}) at the left of the
 328     staff."
 329      '(InstrumentName)
 330      '(
 331       instrument
 332       instr
 333       )))
 334
 335    (cons
 336     'Engraver_group_engraver
 337     (engraver-description
 338      "Engraver_group_engraver"
 339      "A group of engravers taken together"
 340      '()
 341      '(
 342       )))
 343
 344    (cons
 345     'Key_engraver
 346     (engraver-description
 347      "Key_engraver"
 348      ""
 349      '(KeySignature
 350        )
 351      '( keySignature explicitKeySignatureVisibility createKeyOnClefChange keyAccidentalOrder keySignature )))
 352
 353    (cons 'Lyric_engraver
 354          (engraver-description
 355           "Lyric_engraver"
 356           ""
 357           '()
 358           '(
 359            ;; FIXME
 360            )))
 361
 362    (cons 'Lyric_phrasing_engraver
 363          (engraver-description
 364           "Lyric_phrasing_engraver"
 365           ""
 366           '()
 367           '(
 368            automaticPhrasing
 369            weAreGraceContext
 370            melismaEngraverBusy
 371            associatedVoice
 372            phrasingPunctuation
 373            )))
 374
 375    (cons
 376     'Mark_engraver
 377     (engraver-description
 378      "Mark_engraver"
 379      ""
 380      '(RehearsalMark)
 381      '(
 382
 383       rehearsalMark
 384       staffsFound
 385       )))
 386
 387
 388    (cons
 389     'Melisma_engraver
 390     (engraver-description
 391      "Melisma_engraver"
 392      ""
 393      '()
 394      '(
 395
 396       melismaBusy
 397       slurMelismaBusy
 398       tieMelismaBusy
 399       beamMelismaBusy
 400       )))
 401
 402
 403    (cons
 404     'Multi_measure_rest_engraver
 405     (engraver-description
 406      "Multi_measure_rest_engraver"
 407      "Engraves multi-measure rests that are produced with @code{R}.  Reads
 408 measurePosition and currentBarNumber to determine what number to print over the MultiMeasureRest
 409    "
 410      '(MultiMeasureRest)
 411      '(currentBarNumber currentCommandColumn measurePosition
 412       )))
 413
 414    (cons
 415     'Note_heads_engraver
 416     (engraver-description
 417      "Note_heads_engraver"
 418      "Generate one or more noteheads from Music of type Note_req."
 419      '(NoteHead Dots)
 420      '(
 421       )))
 422
 423    (cons
 424     'Note_head_line_engraver
 425     (engraver-description
 426      "Note_head_line_engraver"
 427      "Engrave a line between two note heads, for example a glissando.
 428 If followVoice is set, staff switches also generate a line."
 429      '(Glissando VoiceFollower)
 430      '(followVoice)))
 431
 432    (cons
 433     'Note_name_engraver
 434     (engraver-description
 435      "Note_name_engraver"
 436      ""
 437      '(NoteName)
 438      '(
 439       )))
 440
 441
 442    (cons
 443     'Output_property_engraver
 444     (engraver-description
 445      "Output_property_engraver"
 446      "Interpret Music of Output_property type, and apply a function
 447 to any Graphic objects that satisfies the predicate."
 448      '()
 449      '(
 450       )))
 451
 452
 453    (cons
 454     'Piano_pedal_engraver
 455     (engraver-description
 456      "Piano_pedal_engraver"
 457      "Engrave piano pedal symbols."
 458      '(SostenutoPedal SustainPedal UnaCordaPedal)
 459      '(pedalSostenutoStrings pedalSustainStrings pedalUnaCordaStrings
 460       )))
 461
 462    (cons
 463     'Pitch_squash_engraver
 464     (engraver-description
 465      "Pitch_squash_engraver"
 466      "Treat all pitches as middle C.  Note that the notes move, but
 467 the locations of accidentals stay the same.
 468 Set the position field of all note heads to zero. This useful for
 469 making a single line staff that demonstrates the rhythm of a melody."
 470      '()
 471      '(
 472       squashedPosition
 473       )))
 474
 475    (cons
 476     'Property_engraver
 477     (engraver-description
 478      "Property_engraver"
 479 "This is a engraver that converts \property settings into
 480 back-end grob-property settings. Example: Voice.stemLength will set
 481 #'length in all Stem objects.
 482
 483 Due to CPU and memory requirements, the use of this engraver is deprecated."
 484      '()
 485      '(Generic_property_list)
 486       ))
 487
 488
 489    (cons
 490     'Repeat_acknowledge_engraver
 491     (engraver-description
 492      "Repeat_acknowledge_engraver"
 493
 494      "Acknowledge repeated music, and convert the contents of
 495 repeatCommands ainto an appropriate setting for whichBar"
 496      '()
 497      '(
 498       repeatCommands
 499       whichBar
 500
 501       )))
 502
 503
 504    (cons
 505     'Rest_collision_engraver
 506     (engraver-description
 507      "Rest_collision_engraver"
 508      "Handles collisions of rests."
 509      '(RestCollision)
 510      '(
 511       )))
 512
 513
 514    (cons
 515     'Rest_engraver
 516     (engraver-description
 517      "Rest_engraver"
 518      ""
 519       '(Rest Dots)
 520    '(
 521       )))
 522
 523
 524    (cons
 525     'Rhythmic_column_engraver
 526     (engraver-description
 527      "Rhythmic_column_engraver"
 528      "Generates NoteColumn, an objects that groups stems, noteheads and rests."
 529      '(NoteColumn)
 530      '(
 531       )))
 532
 533
 534    (cons
 535     'Script_column_engraver
 536     (engraver-description
 537      "Script_column_engraver"
 538      ""
 539      '(ScriptColumn)
 540      '(
 541       )))
 542
 543
 544    (cons
 545     'Script_engraver
 546     (engraver-description
 547      "Script_engraver"
 548      "    Handles note ornaments generated by @code{\script}.
 549 "
 550      '(Script)
 551      '(
 552       scriptDefinitions
 553       scriptHorizontal
 554       )))
 555
 556    (cons
 557     'Score_engraver
 558     (engraver-description
 559      "Score_engraver"
 560      "Top level engraver. Takes care of generating columns and the complete  system (ie. LineOfScore)
 561
 562 This engraver decides whether a column is breakable. The default is
 563 that a column is always breakable. However, when every Bar_engraver
 564 that does not have a barline at a certain point will call
 565 Score_engraver::forbid_breaks to stop linebreaks.  In practice, this
 566 means that you can make a breakpoint by creating a barline (assuming
 567 that there are no beams or notes that prevent a breakpoint.)
 568
 569 "
 570      '(LineOfScore PaperColumn NonMusicalPaperColumn)
 571      '(
 572       currentMusicalColumn
 573       currentCommandColumn
 574       )))
 575
 576    (cons 'Skip_req_swallow_translator
 577          (engraver-description
 578           "Skip_req_swallow_translator"
 579           ""
 580           '()
 581           '(
 582            ;; FIXME
 583            )))
 584
 585    (cons
 586     'Slur_engraver
 587     (engraver-description
 588      "Slur_engraver"
 589      "Build slurs from Slur_reqs"
 590      '(Slur)
 591
 592      '(
 593       slurBeginAttachment
 594       slurEndAttachment
 595       slurMelismaBusy
 596       )))
 597
 598
 599    (cons
 600     'Spacing_engraver
 601     (engraver-description
 602      "Spacing_engraver"
 603      "make a SpacingSpanner and do bookkeeping of shortest starting and playing notes  "
 604      '(SpacingSpanner)
 605      '(
 606       )))
 607
 608
 609    (cons
 610     'Span_arpeggio_engraver
 611     (engraver-description
 612      "Span_arpeggio_engraver"
 613      ""
 614      '(Arpeggio)
 615      '(
 616       connectArpeggios
 617       )))
 618
 619
 620    (cons
 621     'Span_bar_engraver
 622     (engraver-description
 623      "Span_bar_engraver"
 624      "This engraver makes cross-staff barlines: It catches all normal
 625 bar lines, and draws a single span-bar across them."
 626
 627      '(SpanBar)
 628      '(
 629       )))
 630
 631
 632    (cons
 633     'Staff_symbol_engraver
 634     (engraver-description
 635      "Staff_symbol_engraver"
 636      "create the constellation of five (default) staff lines."
 637      '(StaffSymbol)
 638      '(
 639       )))
 640
 641
 642    (cons
 643     'Stanza_number_engraver
 644     (engraver-description
 645      "Stanza_number_engraver"
 646      ""
 647      '(StanzaNumber
 648        )
 649      '(
 650       stz
 651       stanza
 652       )))
 653
 654
 655
 656    (cons
 657     'System_start_delimiter_engraver
 658     (engraver-description
 659      "System_start_delimiter_engraver"
 660      "creates a SystemStartDelimiter spanner"
 661      '(SystemStartDelimiter)
 662      '(
 663       )))
 664
 665
 666    (cons
 667     'Text_engraver
 668     (engraver-description
 669      "Text_engraver"
 670      "Create text-scripts"
 671      '(TextScript)
 672      '(
 673       scriptHorizontal
 674       textNonEmpty
 675       )))
 676
 677
 678    (cons
 679     'Text_spanner_engraver
 680     (engraver-description
 681      "Text_spanner_engraver"
 682      "Create text spanner from a  Span_req "
 683      '(TextSpanner)
 684      '(
 685       )))
 686
 687
 688    (cons
 689     'Thread_devnull_engraver
 690     (engraver-description
 691      "Thread_devnull_engraver"
 692      "Kill elements whenever we are Voice called `two' and either
 693 unison, unisilence or soloADue is set.@footnote{On unix systems, the
 694 file @file{/dev/null} is special device: anything written to it is
 695 discarded.}. This engraver works closely together with the part
 696 combiner.  When the part combiner notices that two threads are
 697 identical, it tells the @code{Thread_devnull_engraver} to discard
 698 everything in the second thread.
 699 "
 700
 701      '()
 702      '()))
 703
 704
 705    (cons
 706     'Tie_engraver
 707     (engraver-description
 708      "Tie_engraver"
 709      "Generate ties between noteheads of equal pitch."
 710      '(Tie TieColumn)
 711      '(sparseTies
 712       tieMelismaBusy
 713       )))
 714
 715
 716    (cons
 717     'Time_signature_engraver
 718     (engraver-description
 719      "Time_signature_engraver"
 720      "Create a TimeSignature whenever @code{timeSignatureFraction} changes"
 721      '(TimeSignature)
 722      '(
 723       )))
 724
 725
 726    (cons
 727     'Timing_engraver
 728     (engraver-description
 729      "Timing_engraver"
 730      " Responsible for synchronizing timing information from staffs.
 731     Normally in @code{Score}.  In order to create polyrhythmic music,
 732     this engraver should be removed from @code{Score} and placed in
 733     @code{Staff}."
 734      '()
 735      '(
 736       timeSignatureFraction
 737       barCheckNoSynchronize
 738       barNonAuto
 739       whichBar
 740       barAlways
 741       defaultBarType
 742       skipBars
 743       timing
 744       oneBeat
 745       measureLength
 746       measurePosition
 747       currentBarNumber
 748       )))
 749
 750
 751    (cons
 752     'Tuplet_engraver
 753     (engraver-description
 754      "Tuplet_engraver"
 755      "Catch Time_scaled_music and generate appropriate bracket  "
 756      '( TupletBracket)
 757      '(tupletNumberFormatFunction tupletSpannerDuration tupletInvisible)))
 758
 759
 760    (cons
 761     'Vertical_align_engraver
 762     (engraver-description
 763      "Vertical_align_engraver"
 764      "Catch Vertical axis groups and stack them."
 765      '(VerticalAlignment)
 766      '(
 767       )))
 768
 769
 770    (cons
 771     'Voice_devnull_engraver
 772     (engraver-description
 773      "Voice_devnull_engraver"
 774      "Kill off certain items and spanners if we're Voice `two' and unison or unisilence is set."
 775      '()
 776      '(
 777       )))
 778    ))
 779
 780
 781 (set! engraver-description-alist
 782       (sort engraver-description-alist alist<?))
 783
 784 (define context-description-alist
 785   '(
 786 (Grace . "
 787     The context for handling grace notes.  It is instantiated
 788     automatically when you use @code{\grace}.  Basically, it is an
 789     `embedded' miniature of the Score context.  Since this context
 790     needs special interaction with the rest of LilyPond, you should
 791     not explicitly instantiate it.
 792 ")
 793 (LyricsVoice . "
 794     Corresponds to a voice with lyrics.  Handles the printing of a
 795     single line of lyrics.
 796 ")
 797 (Thread . "
 798     Handles note heads, and is contained in the Voice context.  You
 799     have to instantiate this explicitly if you want to adjust the
 800     style of individual note heads.
 801 ")
 802 (Voice . "
 803     Corresponds to a voice on a staff.  This context handles the
 804     conversion of dynamic signs, stems, beams, super- and subscripts,
 805     slurs, ties, and rests.
 806
 807     You have to instantiate this explicitly if you want to have
 808     multiple voices on the same staff.")
 809
 810 (ChordNamesVoice . "
 811     A voice with chord names.  Handles printing of a line of chord
 812     names.")
 813
 814 (ChordNames . "
 815     Typesets chord names.  Can contain @code{ChordNamesVoice}
 816     contexts.")
 817
 818 (Lyrics . "
 819     Typesets lyrics.  It can contain @code{LyricsVoice} contexts.
 820 ")
 821 (Staff . "
 822     Handles clefs, bar lines, keys, accidentals.  It can contain
 823     @code{Voice} contexts.
 824 ")
 825 (RhythmicStaff . "
 826     A context like @code{Staff} but for printing rhythms.  Pitches are
 827     ignored; the notes are printed on one line.  It can contain
 828     @code{Voice} contexts.
 829 ")
 830 (GrandStaff . "
 831     Contains @code{Staff} or @code{RhythmicStaff} contexts.  It adds a
 832     brace on the left side, grouping the staffs together.  The bar
 833     lines of the contained staffs are connected vertically.  It can
 834     contain @code{Staff} contexts.")
 835
 836 (PianoStaff . "
 837     Just like @code{GrandStaff} but with @code{minVerticalAlign} set
 838     equal to @code{maxVerticalAlign} so that interstaff beaming and
 839     slurring can be used.")
 840
 841 (StaffGroup . "
 842     Contains @code{Staff} or @code{RhythmicStaff} contexts.  Adds a
 843     bracket on the left side, grouping the staffs together.  The bar
 844     lines of the contained staffs are connected vertically.  It can
 845     contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
 846     @code{Lyrics} contexts.
 847 ")
 848 (ChoirStaff . "
 849     Identical to @code{StaffGroup} except that the contained staffs
 850     are not connected vertically.
 851 ")
 852 (Score . "
 853     This is the top level notation context.  No other context can
 854     contain a @code{Score} context.  This context handles the
 855     administration of time signatures.  It also makes sure that items
 856     such as clefs, time signatures, and key-signatures are aligned
 857     across staffs.  It can contain @code{Lyrics}, @code{Staff},
 858     @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
 859     @code{ChoirStaff} contexts.
 860
 861     You cannot explicitly instantiate a Score context (since it is
 862     not contained in any other context).  It is instantiated
 863     automatically when an output definition (a @code{\score} or
 864     @code{\paper} block) is processed.
 865 ")
 866 )
 867 )
 868
 869 (set! context-description-alist
 870       (sort context-description-alist alist<?))
 871