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      '(CONTEXTNAMEVerticalExtent CONTEXTNAMEMinimumVerticalExtent CONTEXTNAMExtraVerticalExtent)
  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      '(TextScript)
 117      '(
 118       combineParts
 119       soloADue
 120       soloText
 121       soloIIText
 122       aDueText
 123       split-interval
 124       unison
 125       solo
 126       unisilence
 127       unirhythm
 128       )))
 129
 130    (cons
 131     'Align_note_column_engraver
 132     (engraver-description
 133      "Align_note_column_engraver"
 134      "Generate object to put grace notes from left to right."
 135      '(GraceAlignment)
 136      '(
 137
 138       graceAlignPosition
 139       graceAccidentalSpace
 140       )))
 141
 142    (cons
 143     'Arpeggio_engraver
 144     (engraver-description
 145      "Arpeggio_engraver"
 146      "Generate an Arpeggio from a Arpeggio_req"
 147      '(Arpeggio)
 148      '(
 149       )))
 150
 151    (cons
 152    'Auto_beam_engraver
 153     (engraver-description
 154      "Auto_beam_engraver"
 155      "Generate beams based on measure characteristics and observed
 156 Stems.  Uses beatLength, measureLength and measurePosition to decide
 157 when to start and stop a beam.  Overriding beaming is done through
 158 @ref{Stem_engraver} properties stemLeftBeamCount and
 159 stemRightBeamCount.
 160 "
 161      '(
 162        Beam)
 163      '(
 164       noAutoBeaming
 165       autoBeamSettings)))
 166
 167    (cons
 168     'Bar_engraver
 169     (engraver-description
 170      "Bar_engraver"
 171      "Create barlines. This engraver is controlled through the
 172 @code{whichBar} property. If it has no bar line to create, it will forbid a linebreak at this point"
 173      '(BarLine)
 174      '(
 175       whichBar
 176       staffsFound
 177       )))
 178
 179
 180    (cons
 181     'Bar_number_engraver
 182     (engraver-description
 183      "Bar_number_engraver"
 184      "A bar number is created whenever measurePosition is zero. It is
 185 put on top of all staffs, and appears only at  left side of the staff."
 186      '(BarNumber)
 187      '(
 188       currentBarNumber
 189       )))
 190
 191
 192    (cons
 193     'Beam_engraver
 194     (engraver-description
 195      "Beam_engraver"
 196      "Handles Beam_requests by engraving Beams.    If omitted, then notes will be
 197     printed with flags instead of beams."
 198      '(Beam)
 199      '(
 200       beamMelismaBusy
 201       )))
 202
 203    (cons
 204     'Break_align_engraver
 205     (engraver-description
 206      "Break_align_engraver"
 207      "Align graphic elements with corresponding break-align-symbols into groups, and order the groups according to breakAlignOrder"
 208      '(BreakAlignment BreakAlignGroup LeftEdge)
 209      '(
 210       breakAlignOrder
 211
 212       )))
 213
 214
 215    (cons
 216     'Breathing_sign_engraver
 217     (engraver-description
 218      "Breathing_sign_engraver"
 219      ""
 220      '(BreathingSign)
 221      '(
 222       )))
 223
 224
 225    (cons
 226     'Chord_name_engraver
 227     (engraver-description
 228      "Chord_name_engraver"
 229      "Catch Note_req's, Tonic_reqs, Inversion_reqs, Bass_req
 230 and generate the appropriate chordname."
 231      '(ChordName)
 232      '(
 233       chordInversion
 234       drarnChords
 235       )))
 236
 237
 238    (cons
 239     'Chord_tremolo_engraver
 240     (engraver-description
 241      "Chord_tremolo_engraver"
 242      "Generates beams for the \repeat X tremolo ... construct"
 243      '(Beam)
 244      '(
 245       )))
 246
 247
 248
 249    (cons
 250     'Collision_engraver
 251     (engraver-description
 252      "Collision_engraver"
 253      ""
 254      '(NoteCollision
 255        )
 256      '(
 257       )))
 258
 259    (cons
 260     'Custos_engraver
 261     (engraver-description
 262      "Custos_engraver"
 263      ""
 264      '(Custos)
 265      '(
 266       )))
 267
 268
 269    (cons
 270     'Dot_column_engraver
 271     (engraver-description
 272      "Dot_column_engraver"
 273      " Engraves dots on dotted notes shifted to the right of the note.
 274 If omitted, then dots appear on top of the notes.
 275 "
 276      '(DotColumn
 277        )
 278      '(
 279       )))
 280
 281
 282    (cons
 283     'Dynamic_engraver
 284     (engraver-description
 285      "Dynamic_engraver"
 286      ""
 287      '(DynamicLineSpanner
 288        DynamicText Crescendo
 289        TextSpanner)
 290      '(
 291       )))
 292
 293
 294
 295
 296    (cons
 297     'Grace_position_engraver
 298     (engraver-description
 299      "Grace_position_engraver"
 300      "Attach a grace note alignment to a note-column "
 301      '()
 302      '(
 303       )))
 304
 305    (cons
 306     'Grace_engraver_group
 307     (engraver-description
 308      "Grace_engraver_group"
 309      "An engraver that creates a `shielded' context-tree with separate notion of time"
 310      '()
 311      '(
 312       )))
 313
 314
 315    (cons
 316     'Instrument_name_engraver
 317     (engraver-description
 318      "Instrument_name_engraver"
 319      " Prints the name of the instrument (specified by
 320     @code{Staff.instrument} and @code{Staff.instr}) at the left of the
 321     staff."
 322      '(InstrumentName)
 323      '(
 324       instrument
 325       instr
 326       )))
 327
 328    (cons
 329     'Engraver_group_engraver
 330     (engraver-description
 331      "Engraver_group_engraver"
 332      "A group of engravers taken together"
 333      '()
 334      '(
 335       )))
 336
 337    (cons
 338     'Key_engraver
 339     (engraver-description
 340      "Key_engraver"
 341      ""
 342      '(KeySignature
 343        )
 344      '(
 345
 346       keySignature
 347       keyOctaviation
 348       explicitKeySignatureVisibility
 349       createKeyOnClefChange
 350       keyAccidentalOrder
 351       keySignature
 352       )))
 353
 354    (cons 'Lyric_engraver
 355          (engraver-description
 356           "Lyric_engraver"
 357           ""
 358           '()
 359           '(
 360            ;; FIXME
 361            )))
 362
 363    (cons 'Lyric_phrasing_engraver
 364          (engraver-description
 365           "Lyric_phrasing_engraver"
 366           ""
 367           '()
 368           '(
 369            automaticPhrasing
 370            weAreGraceContext
 371            melismaEngraverBusy
 372            associatedVoice
 373            phrasingPunctuation
 374            )))
 375
 376    (cons
 377     'Mark_engraver
 378     (engraver-description
 379      "Mark_engraver"
 380      ""
 381      '(RehearsalMark)
 382      '(
 383
 384       rehearsalMark
 385       staffsFound
 386       )))
 387
 388
 389    (cons
 390     'Melisma_engraver
 391     (engraver-description
 392      "Melisma_engraver"
 393      ""
 394      '()
 395      '(
 396
 397       melismaBusy
 398       slurMelismaBusy
 399       tieMelismaBusy
 400       beamMelismaBusy
 401       )))
 402
 403
 404    (cons
 405     'Multi_measure_rest_engraver
 406     (engraver-description
 407      "Multi_measure_rest_engraver"
 408      "Engraves multi-measure rests that are produced with @code{R}.  Reads
 409 measurePosition and currentBarNumber to determine what number to print over the MultiMeasureRest
 410    "
 411      '(MultiMeasureRest)
 412      '(
 413       )))
 414
 415    (cons
 416     'Note_heads_engraver
 417     (engraver-description
 418      "Note_heads_engraver"
 419      "Generate one or more noteheads from Music of type Note_req."
 420      '(NoteHead Dots)
 421      '(
 422       )))
 423
 424    (cons
 425     'Note_head_line_engraver
 426     (engraver-description
 427      "Note_head_line_engraver"
 428      "Engrave a line between two note heads."
 429      '(Glissando FollowThread)
 430      '(
 431       )))
 432
 433    (cons
 434     'Note_name_engraver
 435     (engraver-description
 436      "Note_name_engraver"
 437      ""
 438      '(NoteName)
 439      '(
 440       )))
 441
 442
 443    (cons
 444     'Output_property_engraver
 445     (engraver-description
 446      "Output_property_engraver"
 447      "Interpret Music of Output_property type, and apply a function
 448 to any Graphic objects that satisfies the predicate."
 449      '()
 450      '(
 451       )))
 452
 453
 454    (cons
 455     'Piano_pedal_engraver
 456     (engraver-description
 457      "Piano_pedal_engraver"
 458      "engrave Piano pedals symbols."
 459      '(SostenutoPedal SustainPedal UnaChordaPedal)
 460      '(
 461
 462         startSustain
 463         stopSustain
 464         stopStartSustain
 465         startUnaChorda
 466         stopUnaChorda
 467       )))
 468
 469    (cons
 470     'Pitch_squash_engraver
 471     (engraver-description
 472      "Pitch_squash_engraver"
 473      "Treat all pitches as middle C.  Note that the notes move, but
 474 the locations of accidentals stay the same.
 475 Set the position field of all note heads to zero. This useful for
 476 making a single line staff that demonstrates the rhythm of a melody."
 477      '()
 478      '(
 479       squashedPosition
 480       )))
 481
 482    (cons
 483     'Property_engraver
 484     (engraver-description
 485      "Property_engraver"
 486 "This is a engraver that converts \property settings into
 487 back-end element-property settings. Example: Voice.stemLength will set
 488 #'length in all Stem objects.
 489
 490 Due to CPU and memory requirements, the use of this engraver is deprecated."
 491      '()
 492      '(Generic_property_list)
 493       ))
 494
 495
 496    (cons
 497     'Repeat_acknowledge_engraver
 498     (engraver-description
 499      "Repeat_acknowledge_engraver"
 500
 501      "Acknowledge repeated music, and convert the contents of
 502 repeatCommands ainto an appropriate setting for whichBar"
 503      '()
 504      '(
 505       repeatCommands
 506       whichBar
 507
 508       )))
 509
 510
 511    (cons
 512     'Rest_collision_engraver
 513     (engraver-description
 514      "Rest_collision_engraver"
 515      "Handles collisions of rests."
 516      '(RestCollision)
 517      '(
 518       )))
 519
 520
 521    (cons
 522     'Rest_engraver
 523     (engraver-description
 524      "Rest_engraver"
 525      ""
 526       '(Rest Dots)
 527    '(
 528       )))
 529
 530
 531    (cons
 532     'Rhythmic_column_engraver
 533     (engraver-description
 534      "Rhythmic_column_engraver"
 535      "Generates NoteColumn, an objects that groups stems, noteheads and rests."
 536      '(NoteColumn)
 537      '(
 538       )))
 539
 540
 541    (cons
 542     'Script_column_engraver
 543     (engraver-description
 544      "Script_column_engraver"
 545      ""
 546      '(ScriptColumn)
 547      '(
 548       )))
 549
 550
 551    (cons
 552     'Script_engraver
 553     (engraver-description
 554      "Script_engraver"
 555      "    Handles note ornaments generated by @code{\script}.
 556 "
 557      '(Script)
 558      '(
 559       scriptDefinitions
 560       scriptHorizontal
 561       )))
 562
 563    (cons
 564     'Score_engraver
 565     (engraver-description
 566      "Score_engraver"
 567      "Top level engraver. Takes care of generating columns and the complete  system (ie. LineOfScore)
 568
 569 This engraver decides whether a column is breakable. The default is
 570 that a column is always breakable. However, when every Bar_engraver
 571 that does not have a barline at a certain point will call
 572 Score_engraver::forbid_breaks to stop linebreaks.  In practice, this
 573 means that you can make a breakpoint by creating a barline (assuming
 574 that there are no beams or notes that prevent a breakpoint.)
 575
 576 "
 577      '(LineOfScore PaperColumn NonMusicalPaperColumn)
 578      '(
 579       currentMusicalColumn
 580       currentCommandColumn
 581       )))
 582
 583    (cons 'Skip_req_swallow_translator
 584          (engraver-description
 585           "Skip_req_swallow_translator"
 586           ""
 587           '()
 588           '(
 589            ;; FIXME
 590            )))
 591
 592    (cons
 593     'Slur_engraver
 594     (engraver-description
 595      "Slur_engraver"
 596      "Build slurs from Slur_reqs"
 597      '(Slur)
 598
 599      '(
 600       slurBeginAttachment
 601       slurEndAttachment
 602       slurMelismaBusy
 603       )))
 604
 605
 606    (cons
 607     'Spacing_engraver
 608     (engraver-description
 609      "Spacing_engraver"
 610      "make a SpacingSpanner and do bookkeeping of shortest starting and playing notes  "
 611      '(SpacingSpanner)
 612      '(
 613       )))
 614
 615
 616    (cons
 617     'Span_arpeggio_engraver
 618     (engraver-description
 619      "Span_arpeggio_engraver"
 620      ""
 621      '(Arpeggio)
 622      '(
 623       connectArpeggios
 624       )))
 625
 626
 627    (cons
 628     'Span_bar_engraver
 629     (engraver-description
 630      "Span_bar_engraver"
 631      "This engraver makes cross-staff barlines: It catches all normal
 632 bar lines, and draws a single span-bar across them."
 633
 634      '(SpanBar)
 635      '(
 636       )))
 637
 638
 639    (cons
 640     'Staff_symbol_engraver
 641     (engraver-description
 642      "Staff_symbol_engraver"
 643      "create the constellation of five (default) staff lines."
 644      '(StaffSymbol)
 645      '(
 646       )))
 647
 648
 649    (cons
 650     'Stanza_number_engraver
 651     (engraver-description
 652      "Stanza_number_engraver"
 653      ""
 654      '(StanzaNumber
 655        )
 656      '(
 657       stz
 658       stanza
 659       )))
 660
 661
 662
 663    (cons
 664     'System_start_delimiter_engraver
 665     (engraver-description
 666      "System_start_delimiter_engraver"
 667      "creates a SystemStartDelimiter spanner"
 668      '(SystemStartDelimiter)
 669      '(
 670       )))
 671
 672
 673    (cons
 674     'Text_engraver
 675     (engraver-description
 676      "Text_engraver"
 677      "Create text-scripts"
 678      '(TextScript)
 679      '(
 680       scriptHorizontal
 681       textNonEmpty
 682       )))
 683
 684
 685    (cons
 686     'Text_spanner_engraver
 687     (engraver-description
 688      "Text_spanner_engraver"
 689      "Create text spanner from a  Span_req "
 690      '(TextSpanner)
 691      '(
 692       )))
 693
 694
 695    (cons
 696     'Thread_devnull_engraver
 697     (engraver-description
 698      "Thread_devnull_engraver"
 699      "Kill elements whenever we are Voice called `two' and
 700 either unison, unisilence or soloADue is set"
 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      '(
 757        TupletBracket)
 758      '(
 759       tupletSpannerDuration
 760       tupletInvisible
 761       )))
 762
 763
 764    (cons
 765     'Vertical_align_engraver
 766     (engraver-description
 767      "Vertical_align_engraver"
 768      "Catch Vertical axis groups and stack them."
 769      '(VerticalAlignment)
 770      '(
 771       )))
 772
 773
 774    (cons
 775     'Voice_devnull_engraver
 776     (engraver-description
 777      "Voice_devnull_engraver"
 778      "Kill off certain items and spanners if we're Voice `two' and unison or unisilence is set."
 779      '()
 780      '(
 781       )))
 782    ))
 783
 784
 785 (set! engraver-description-alist
 786       (sort engraver-description-alist alist<?))
 787
 788 (define context-description-alist
 789   '(
 790 (Grace . "
 791     The context for handling grace notes.  It is instantiated
 792     automatically when you use @code{\grace}.  Basically, it is an
 793     `embedded' miniature of the Score context.  Since this context
 794     needs special interaction with the rest of LilyPond, you should
 795     not explicitly instantiate it.
 796 ")
 797 (LyricsVoice . "
 798     Corresponds to a voice with lyrics.  Handles the printing of a
 799     single line of lyrics.
 800 ")
 801 (Thread . "
 802     Handles note heads, and is contained in the Voice context.  You
 803     have to instantiate this explicitly if you want to adjust the
 804     style of individual note heads.
 805 ")
 806 (Voice . "
 807     Corresponds to a voice on a staff.  This context handles the
 808     conversion of dynamic signs, stems, beams, super- and subscripts,
 809     slurs, ties, and rests.
 810
 811     You have to instantiate this explicitly if you want to have
 812     multiple voices on the same staff.")
 813
 814 (ChordNamesVoice . "
 815     A voice with chord names.  Handles printing of a line of chord
 816     names.")
 817
 818 (ChordNames . "
 819     Typesets chord names.  Can contain @code{ChordNamesVoice}
 820     contexts.")
 821
 822 (Lyrics . "
 823     Typesets lyrics.  It can contain @code{LyricsVoice} contexts.
 824 ")
 825 (Staff . "
 826     Handles clefs, bar lines, keys, accidentals.  It can contain
 827     @code{Voice} contexts.
 828 ")
 829 (RhythmicStaff . "
 830     A context like @code{Staff} but for printing rhythms.  Pitches are
 831     ignored; the notes are printed on one line.  It can contain
 832     @code{Voice} contexts.
 833 ")
 834 (GrandStaff . "
 835     Contains @code{Staff} or @code{RhythmicStaff} contexts.  It adds a
 836     brace on the left side, grouping the staffs together.  The bar
 837     lines of the contained staffs are connected vertically.  It can
 838     contain @code{Staff} contexts.")
 839
 840 (PianoStaff . "
 841     Just like @code{GrandStaff} but with @code{minVerticalAlign} set
 842     equal to @code{maxVerticalAlign} so that interstaff beaming and
 843     slurring can be used.")
 844
 845 (StaffGroup . "
 846     Contains @code{Staff} or @code{RhythmicStaff} contexts.  Adds a
 847     bracket on the left side, grouping the staffs together.  The bar
 848     lines of the contained staffs are connected vertically.  It can
 849     contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
 850     @code{Lyrics} contexts.
 851 ")
 852 (ChoirStaff . "
 853     Identical to @code{StaffGroup} except that the contained staffs
 854     are not connected vertically.
 855 ")
 856 (Score . "
 857     This is the top level notation context.  No other context can
 858     contain a @code{Score} context.  This context handles the
 859     administration of time signatures.  It also makes sure that items
 860     such as clefs, time signatures, and key-signatures are aligned
 861     across staffs.  It can contain @code{Lyrics}, @code{Staff},
 862     @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
 863     @code{ChoirStaff} contexts.
 864
 865     You cannot explicitly instantiate a Score context (since it is
 866     not contained in any other context).  It is instantiated
 867     automatically when an output definition (a @code{\score} or
 868     @code{\paper} block) is processed.
 869 ")
 870 )
 871 )
 872
 873 (set! context-description-alist
 874       (sort context-description-alist alist<?))
 875