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