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