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       noDirection
 120       soloADue
 121       soloText
 122       soloIIText
 123       aDueText
 124       split-interval
 125       unison
 126       solo
 127       unisilence
 128       unirhythm
 129       )))
 130
 131    (cons
 132     'Align_note_column_engraver
 133     (engraver-description
 134      "Align_note_column_engraver"
 135      "Generate object to put grace notes from left to right."
 136      '(GraceAlignment)
 137      '(
 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      '(
 343
 344       keySignature
 345       keyOctaviation
 346       explicitKeySignatureVisibility
 347       createKeyOnClefChange
 348       keyAccidentalOrder
 349       keySignature
 350       )))
 351
 352    (cons 'Lyric_engraver
 353          (engraver-description
 354           "Lyric_engraver"
 355           ""
 356           '()
 357           '(
 358            ;; FIXME
 359            )))
 360
 361    (cons 'Lyric_phrasing_engraver
 362          (engraver-description
 363           "Lyric_phrasing_engraver"
 364           ""
 365           '()
 366           '(
 367            automaticPhrasing
 368            weAreGraceContext
 369            melismaEngraverBusy
 370            associatedVoice
 371            phrasingPunctuation
 372            )))
 373
 374    (cons
 375     'Mark_engraver
 376     (engraver-description
 377      "Mark_engraver"
 378      ""
 379      '(RehearsalMark)
 380      '(
 381
 382       rehearsalMark
 383       staffsFound
 384       )))
 385
 386
 387    (cons
 388     'Melisma_engraver
 389     (engraver-description
 390      "Melisma_engraver"
 391      ""
 392      '()
 393      '(
 394
 395       melismaBusy
 396       slurMelismaBusy
 397       tieMelismaBusy
 398       beamMelismaBusy
 399       )))
 400
 401
 402    (cons
 403     'Multi_measure_rest_engraver
 404     (engraver-description
 405      "Multi_measure_rest_engraver"
 406      "Engraves multi-measure rests that are produced with @code{R}.  Reads
 407 measurePosition and currentBarNumber to determine what number to print over the MultiMeasureRest
 408    "
 409      '(MultiMeasureRest)
 410      '(
 411       )))
 412
 413    (cons
 414     'Note_heads_engraver
 415     (engraver-description
 416      "Note_heads_engraver"
 417      "Generate one or more noteheads from Music of type Note_req."
 418      '(NoteHead Dots)
 419      '(
 420       )))
 421
 422    (cons
 423     'Note_head_line_engraver
 424     (engraver-description
 425      "Note_head_line_engraver"
 426      "Engrave a line between two note heads, for example a glissando.
 427 If followThread is set, staff switches also generate a line."
 428      '(Glissando FollowThread)
 429      '(followThread)))
 430
 431    (cons
 432     'Note_name_engraver
 433     (engraver-description
 434      "Note_name_engraver"
 435      ""
 436      '(NoteName)
 437      '(
 438       )))
 439
 440
 441    (cons
 442     'Output_property_engraver
 443     (engraver-description
 444      "Output_property_engraver"
 445      "Interpret Music of Output_property type, and apply a function
 446 to any Graphic objects that satisfies the predicate."
 447      '()
 448      '(
 449       )))
 450
 451
 452    (cons
 453     'Piano_pedal_engraver
 454     (engraver-description
 455      "Piano_pedal_engraver"
 456      "Engrave piano pedal symbols."
 457      '(SostenutoPedal SustainPedal UnaChordaPedal)
 458      '(pedalSostenutoStrings pedalSustainStrings pedalUnaChordaStrings
 459       )))
 460
 461    (cons
 462     'Pitch_squash_engraver
 463     (engraver-description
 464      "Pitch_squash_engraver"
 465      "Treat all pitches as middle C.  Note that the notes move, but
 466 the locations of accidentals stay the same.
 467 Set the position field of all note heads to zero. This useful for
 468 making a single line staff that demonstrates the rhythm of a melody."
 469      '()
 470      '(
 471       squashedPosition
 472       )))
 473
 474    (cons
 475     'Property_engraver
 476     (engraver-description
 477      "Property_engraver"
 478 "This is a engraver that converts \property settings into
 479 back-end grob-property settings. Example: Voice.stemLength will set
 480 #'length in all Stem objects.
 481
 482 Due to CPU and memory requirements, the use of this engraver is deprecated."
 483      '()
 484      '(Generic_property_list)
 485       ))
 486
 487
 488    (cons
 489     'Repeat_acknowledge_engraver
 490     (engraver-description
 491      "Repeat_acknowledge_engraver"
 492
 493      "Acknowledge repeated music, and convert the contents of
 494 repeatCommands ainto an appropriate setting for whichBar"
 495      '()
 496      '(
 497       repeatCommands
 498       whichBar
 499
 500       )))
 501
 502
 503    (cons
 504     'Rest_collision_engraver
 505     (engraver-description
 506      "Rest_collision_engraver"
 507      "Handles collisions of rests."
 508      '(RestCollision)
 509      '(
 510       )))
 511
 512
 513    (cons
 514     'Rest_engraver
 515     (engraver-description
 516      "Rest_engraver"
 517      ""
 518       '(Rest Dots)
 519    '(
 520       )))
 521
 522
 523    (cons
 524     'Rhythmic_column_engraver
 525     (engraver-description
 526      "Rhythmic_column_engraver"
 527      "Generates NoteColumn, an objects that groups stems, noteheads and rests."
 528      '(NoteColumn)
 529      '(
 530       )))
 531
 532
 533    (cons
 534     'Script_column_engraver
 535     (engraver-description
 536      "Script_column_engraver"
 537      ""
 538      '(ScriptColumn)
 539      '(
 540       )))
 541
 542
 543    (cons
 544     'Script_engraver
 545     (engraver-description
 546      "Script_engraver"
 547      "    Handles note ornaments generated by @code{\script}.
 548 "
 549      '(Script)
 550      '(
 551       scriptDefinitions
 552       scriptHorizontal
 553       )))
 554
 555    (cons
 556     'Score_engraver
 557     (engraver-description
 558      "Score_engraver"
 559      "Top level engraver. Takes care of generating columns and the complete  system (ie. LineOfScore)
 560
 561 This engraver decides whether a column is breakable. The default is
 562 that a column is always breakable. However, when every Bar_engraver
 563 that does not have a barline at a certain point will call
 564 Score_engraver::forbid_breaks to stop linebreaks.  In practice, this
 565 means that you can make a breakpoint by creating a barline (assuming
 566 that there are no beams or notes that prevent a breakpoint.)
 567
 568 "
 569      '(LineOfScore PaperColumn NonMusicalPaperColumn)
 570      '(
 571       currentMusicalColumn
 572       currentCommandColumn
 573       )))
 574
 575    (cons 'Skip_req_swallow_translator
 576          (engraver-description
 577           "Skip_req_swallow_translator"
 578           ""
 579           '()
 580           '(
 581            ;; FIXME
 582            )))
 583
 584    (cons
 585     'Slur_engraver
 586     (engraver-description
 587      "Slur_engraver"
 588      "Build slurs from Slur_reqs"
 589      '(Slur)
 590
 591      '(
 592       slurBeginAttachment
 593       slurEndAttachment
 594       slurMelismaBusy
 595       )))
 596
 597
 598    (cons
 599     'Spacing_engraver
 600     (engraver-description
 601      "Spacing_engraver"
 602      "make a SpacingSpanner and do bookkeeping of shortest starting and playing notes  "
 603      '(SpacingSpanner)
 604      '(
 605       )))
 606
 607
 608    (cons
 609     'Span_arpeggio_engraver
 610     (engraver-description
 611      "Span_arpeggio_engraver"
 612      ""
 613      '(Arpeggio)
 614      '(
 615       connectArpeggios
 616       )))
 617
 618
 619    (cons
 620     'Span_bar_engraver
 621     (engraver-description
 622      "Span_bar_engraver"
 623      "This engraver makes cross-staff barlines: It catches all normal
 624 bar lines, and draws a single span-bar across them."
 625
 626      '(SpanBar)
 627      '(
 628       )))
 629
 630
 631    (cons
 632     'Staff_symbol_engraver
 633     (engraver-description
 634      "Staff_symbol_engraver"
 635      "create the constellation of five (default) staff lines."
 636      '(StaffSymbol)
 637      '(
 638       )))
 639
 640
 641    (cons
 642     'Stanza_number_engraver
 643     (engraver-description
 644      "Stanza_number_engraver"
 645      ""
 646      '(StanzaNumber
 647        )
 648      '(
 649       stz
 650       stanza
 651       )))
 652
 653
 654
 655    (cons
 656     'System_start_delimiter_engraver
 657     (engraver-description
 658      "System_start_delimiter_engraver"
 659      "creates a SystemStartDelimiter spanner"
 660      '(SystemStartDelimiter)
 661      '(
 662       )))
 663
 664
 665    (cons
 666     'Text_engraver
 667     (engraver-description
 668      "Text_engraver"
 669      "Create text-scripts"
 670      '(TextScript)
 671      '(
 672       scriptHorizontal
 673       textNonEmpty
 674       )))
 675
 676
 677    (cons
 678     'Text_spanner_engraver
 679     (engraver-description
 680      "Text_spanner_engraver"
 681      "Create text spanner from a  Span_req "
 682      '(TextSpanner)
 683      '(
 684       )))
 685
 686
 687    (cons
 688     'Thread_devnull_engraver
 689     (engraver-description
 690      "Thread_devnull_engraver"
 691      "Kill elements whenever we are Voice called `two' and
 692 either unison, unisilence or soloADue is set"
 693      '()
 694      '()))
 695
 696
 697    (cons
 698     'Tie_engraver
 699     (engraver-description
 700      "Tie_engraver"
 701      "Generate ties between noteheads of equal pitch."
 702      '(Tie TieColumn)
 703      '(sparseTies
 704       tieMelismaBusy
 705       )))
 706
 707
 708    (cons
 709     'Time_signature_engraver
 710     (engraver-description
 711      "Time_signature_engraver"
 712      "Create a TimeSignature whenever @code{timeSignatureFraction} changes"
 713      '(TimeSignature)
 714      '(
 715       )))
 716
 717
 718    (cons
 719     'Timing_engraver
 720     (engraver-description
 721      "Timing_engraver"
 722      " Responsible for synchronizing timing information from staffs.
 723     Normally in @code{Score}.  In order to create polyrhythmic music,
 724     this engraver should be removed from @code{Score} and placed in
 725     @code{Staff}."
 726      '()
 727      '(
 728       timeSignatureFraction
 729       barCheckNoSynchronize
 730       barNonAuto
 731       whichBar
 732       barAlways
 733       defaultBarType
 734       skipBars
 735       timing
 736       oneBeat
 737       measureLength
 738       measurePosition
 739       currentBarNumber
 740       )))
 741
 742
 743    (cons
 744     'Tuplet_engraver
 745     (engraver-description
 746      "Tuplet_engraver"
 747      "Catch Time_scaled_music and generate appropriate bracket  "
 748      '( TupletBracket)
 749      '(tupletNumberFormatFunction tupletSpannerDuration tupletInvisible)))
 750
 751
 752    (cons
 753     'Vertical_align_engraver
 754     (engraver-description
 755      "Vertical_align_engraver"
 756      "Catch Vertical axis groups and stack them."
 757      '(VerticalAlignment)
 758      '(
 759       )))
 760
 761
 762    (cons
 763     'Voice_devnull_engraver
 764     (engraver-description
 765      "Voice_devnull_engraver"
 766      "Kill off certain items and spanners if we're Voice `two' and unison or unisilence is set."
 767      '()
 768      '(
 769       )))
 770    ))
 771
 772
 773 (set! engraver-description-alist
 774       (sort engraver-description-alist alist<?))
 775
 776 (define context-description-alist
 777   '(
 778 (Grace . "
 779     The context for handling grace notes.  It is instantiated
 780     automatically when you use @code{\grace}.  Basically, it is an
 781     `embedded' miniature of the Score context.  Since this context
 782     needs special interaction with the rest of LilyPond, you should
 783     not explicitly instantiate it.
 784 ")
 785 (LyricsVoice . "
 786     Corresponds to a voice with lyrics.  Handles the printing of a
 787     single line of lyrics.
 788 ")
 789 (Thread . "
 790     Handles note heads, and is contained in the Voice context.  You
 791     have to instantiate this explicitly if you want to adjust the
 792     style of individual note heads.
 793 ")
 794 (Voice . "
 795     Corresponds to a voice on a staff.  This context handles the
 796     conversion of dynamic signs, stems, beams, super- and subscripts,
 797     slurs, ties, and rests.
 798
 799     You have to instantiate this explicitly if you want to have
 800     multiple voices on the same staff.")
 801
 802 (ChordNamesVoice . "
 803     A voice with chord names.  Handles printing of a line of chord
 804     names.")
 805
 806 (ChordNames . "
 807     Typesets chord names.  Can contain @code{ChordNamesVoice}
 808     contexts.")
 809
 810 (Lyrics . "
 811     Typesets lyrics.  It can contain @code{LyricsVoice} contexts.
 812 ")
 813 (Staff . "
 814     Handles clefs, bar lines, keys, accidentals.  It can contain
 815     @code{Voice} contexts.
 816 ")
 817 (RhythmicStaff . "
 818     A context like @code{Staff} but for printing rhythms.  Pitches are
 819     ignored; the notes are printed on one line.  It can contain
 820     @code{Voice} contexts.
 821 ")
 822 (GrandStaff . "
 823     Contains @code{Staff} or @code{RhythmicStaff} contexts.  It adds a
 824     brace on the left side, grouping the staffs together.  The bar
 825     lines of the contained staffs are connected vertically.  It can
 826     contain @code{Staff} contexts.")
 827
 828 (PianoStaff . "
 829     Just like @code{GrandStaff} but with @code{minVerticalAlign} set
 830     equal to @code{maxVerticalAlign} so that interstaff beaming and
 831     slurring can be used.")
 832
 833 (StaffGroup . "
 834     Contains @code{Staff} or @code{RhythmicStaff} contexts.  Adds a
 835     bracket on the left side, grouping the staffs together.  The bar
 836     lines of the contained staffs are connected vertically.  It can
 837     contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
 838     @code{Lyrics} contexts.
 839 ")
 840 (ChoirStaff . "
 841     Identical to @code{StaffGroup} except that the contained staffs
 842     are not connected vertically.
 843 ")
 844 (Score . "
 845     This is the top level notation context.  No other context can
 846     contain a @code{Score} context.  This context handles the
 847     administration of time signatures.  It also makes sure that items
 848     such as clefs, time signatures, and key-signatures are aligned
 849     across staffs.  It can contain @code{Lyrics}, @code{Staff},
 850     @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
 851     @code{ChoirStaff} contexts.
 852
 853     You cannot explicitly instantiate a Score context (since it is
 854     not contained in any other context).  It is instantiated
 855     automatically when an output definition (a @code{\score} or
 856     @code{\paper} block) is processed.
 857 ")
 858 )
 859 )
 860
 861 (set! context-description-alist
 862       (sort context-description-alist alist<?))
 863