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