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     'Property_engraver
 440     (engraver-description
 441      "Property_engraver"
 442 "This is a engraver that converts \property settings into
 443 back-end grob-property settings. Example: Voice.stemLength will set
 444 #'length in all Stem objects.
 445
 446 Due to CPU and memory requirements, the use of this engraver is deprecated."
 447      '()
 448      '(Generic_property_list)
 449       ))
 450
 451
 452    (cons
 453     'Repeat_acknowledge_engraver
 454     (engraver-description
 455      "Repeat_acknowledge_engraver"
 456
 457      "Acknowledge repeated music, and convert the contents of
 458 repeatCommands ainto an appropriate setting for whichBar"
 459      '()
 460      '(
 461       repeatCommands
 462       whichBar
 463
 464       )))
 465
 466
 467    (cons
 468     'Rest_collision_engraver
 469     (engraver-description
 470      "Rest_collision_engraver"
 471      "Handles collisions of rests."
 472      '(RestCollision)
 473      '(
 474       )))
 475
 476
 477    (cons
 478     'Rest_engraver
 479     (engraver-description
 480      "Rest_engraver"
 481      ""
 482       '(Rest Dots)
 483    '(
 484       )))
 485
 486
 487    (cons
 488     'Rhythmic_column_engraver
 489     (engraver-description
 490      "Rhythmic_column_engraver"
 491      "Generates NoteColumn, an objects that groups stems, noteheads and rests."
 492      '(NoteColumn)
 493      '(
 494       )))
 495
 496
 497    (cons
 498     'Script_column_engraver
 499     (engraver-description
 500      "Script_column_engraver"
 501      ""
 502      '(ScriptColumn)
 503      '(
 504       )))
 505
 506
 507    (cons
 508     'Script_engraver
 509     (engraver-description
 510      "Script_engraver"
 511      "    Handles note ornaments generated by @code{\script}.
 512 "
 513      '(Script)
 514      '(
 515       scriptDefinitions
 516       scriptHorizontal
 517       )))
 518
 519    (cons
 520     'Score_engraver
 521     (engraver-description
 522      "Score_engraver"
 523      "Top level engraver. Takes care of generating columns and the complete  system (ie. LineOfScore)
 524
 525 This engraver decides whether a column is breakable. The default is
 526 that a column is always breakable. However, when every Bar_engraver
 527 that does not have a barline at a certain point will call
 528 Score_engraver::forbid_breaks to stop linebreaks.  In practice, this
 529 means that you can make a breakpoint by creating a barline (assuming
 530 that there are no beams or notes that prevent a breakpoint.)
 531
 532 "
 533      '(LineOfScore PaperColumn NonMusicalPaperColumn)
 534      '(
 535       currentMusicalColumn
 536       currentCommandColumn
 537       )))
 538
 539    (cons 'Skip_req_swallow_translator
 540          (engraver-description
 541           "Skip_req_swallow_translator"
 542           ""
 543           '()
 544           '(
 545            ;; FIXME
 546            )))
 547
 548    (cons
 549     'Slur_engraver
 550     (engraver-description
 551      "Slur_engraver"
 552      "Build slurs from Slur_reqs"
 553      '(Slur)
 554
 555      '(
 556       slurBeginAttachment
 557       slurEndAttachment
 558       slurMelismaBusy
 559       )))
 560
 561
 562    (cons
 563     'Spacing_engraver
 564     (engraver-description
 565      "Spacing_engraver"
 566      "make a SpacingSpanner and do bookkeeping of shortest starting and playing notes  "
 567      '(SpacingSpanner)
 568      '(
 569       )))
 570
 571
 572    (cons
 573     'Span_arpeggio_engraver
 574     (engraver-description
 575      "Span_arpeggio_engraver"
 576      ""
 577      '(Arpeggio)
 578      '(
 579       connectArpeggios
 580       )))
 581
 582
 583    (cons
 584     'Span_bar_engraver
 585     (engraver-description
 586      "Span_bar_engraver"
 587      "This engraver makes cross-staff barlines: It catches all normal
 588 bar lines, and draws a single span-bar across them."
 589
 590      '(SpanBar)
 591      '(
 592       )))
 593
 594
 595    (cons
 596     'Staff_symbol_engraver
 597     (engraver-description
 598      "Staff_symbol_engraver"
 599      "create the constellation of five (default) staff lines."
 600      '(StaffSymbol)
 601      '(
 602       )))
 603
 604
 605    (cons
 606     'Stanza_number_engraver
 607     (engraver-description
 608      "Stanza_number_engraver"
 609      ""
 610      '(StanzaNumber
 611        )
 612      '(
 613       stz
 614       stanza
 615       )))
 616
 617
 618
 619    (cons
 620     'System_start_delimiter_engraver
 621     (engraver-description
 622      "System_start_delimiter_engraver"
 623      "creates a SystemStartDelimiter spanner"
 624      '(SystemStartDelimiter)
 625      '(
 626       )))
 627
 628
 629    (cons
 630     'Text_engraver
 631     (engraver-description
 632      "Text_engraver"
 633      "Create text-scripts"
 634      '(TextScript)
 635      '(
 636       scriptHorizontal
 637       textNonEmpty
 638       )))
 639
 640
 641    (cons
 642     'Text_spanner_engraver
 643     (engraver-description
 644      "Text_spanner_engraver"
 645      "Create text spanner from a  Span_req "
 646      '(TextSpanner)
 647      '(
 648       )))
 649
 650
 651    (cons
 652     'Thread_devnull_engraver
 653     (engraver-description
 654      "Thread_devnull_engraver"
 655      "Kill elements whenever we are Voice called `two' and either
 656 unison, unisilence or soloADue is set.@footnote{On unix systems, the
 657 file @file{/dev/null} is special device: anything written to it is
 658 discarded.}. This engraver works closely together with the part
 659 combiner.  When the part combiner notices that two threads are
 660 identical, it tells the @code{Thread_devnull_engraver} to discard
 661 everything in the second thread.
 662 "
 663
 664      '()
 665      '()))
 666
 667
 668    (cons
 669     'Tie_engraver
 670     (engraver-description
 671      "Tie_engraver"
 672      "Generate ties between noteheads of equal pitch."
 673      '(Tie TieColumn)
 674      '(sparseTies
 675       tieMelismaBusy
 676       )))
 677
 678
 679    (cons
 680     'Time_signature_engraver
 681     (engraver-description
 682      "Time_signature_engraver"
 683      "Create a TimeSignature whenever @code{timeSignatureFraction} changes"
 684      '(TimeSignature)
 685      '(
 686       )))
 687
 688
 689    (cons
 690     'Timing_engraver
 691     (engraver-description
 692      "Timing_engraver"
 693      " Responsible for synchronizing timing information from staves.
 694     Normally in @code{Score}.  In order to create polyrhythmic music,
 695     this engraver should be removed from @code{Score} and placed in
 696     @code{Staff}."
 697      '()
 698      '(
 699       timeSignatureFraction
 700       barCheckNoSynchronize
 701       barNonAuto
 702       whichBar
 703       barAlways
 704       defaultBarType
 705       skipBars
 706       timing
 707       oneBeat
 708       measureLength
 709       measurePosition
 710       currentBarNumber
 711       )))
 712
 713
 714    (cons
 715     'Tuplet_engraver
 716     (engraver-description
 717      "Tuplet_engraver"
 718      "Catch Time_scaled_music and generate appropriate bracket  "
 719      '( TupletBracket)
 720      '(tupletNumberFormatFunction tupletSpannerDuration tupletInvisible)))
 721
 722
 723    (cons
 724     'Vertical_align_engraver
 725     (engraver-description
 726      "Vertical_align_engraver"
 727      "Catch Vertical axis groups and stack them."
 728      '(VerticalAlignment)
 729      '(
 730       )))
 731
 732
 733    (cons
 734     'Voice_devnull_engraver
 735     (engraver-description
 736      "Voice_devnull_engraver"
 737      "Kill off certain items and spanners if we're Voice `two' and unison or unisilence is set."
 738      '()
 739      '(
 740       )))
 741    ))
 742
 743
 744 (set! engraver-description-alist
 745       (sort engraver-description-alist alist<?))
 746
 747 (define context-description-alist
 748   '(
 749 (Grace . "
 750     The context for handling grace notes.  It used to be instantiated
 751     automatically when you use @code{\grace}.  Basically, it is an
 752     `embedded' miniature of the Score context.  Since this context
 753     needs special interaction with the rest of LilyPond, you should
 754     not explicitly instantiate it.
 755
 756    DEPRECATED.
 757 ")
 758 (LyricsVoice . "
 759     Corresponds to a voice with lyrics.  Handles the printing of a
 760     single line of lyrics.
 761 ")
 762 (Thread . "
 763     Handles note heads, and is contained in the Voice context.  You
 764     have to instantiate this explicitly if you want to adjust the
 765     style of individual note heads.
 766 ")
 767 (Voice . "
 768     Corresponds to a voice on a staff.  This context handles the
 769     conversion of dynamic signs, stems, beams, super- and subscripts,
 770     slurs, ties, and rests.
 771
 772     You have to instantiate this explicitly if you want to have
 773     multiple voices on the same staff.")
 774
 775 (ChordNamesVoice . "
 776     A voice with chord names.  Handles printing of a line of chord
 777     names.")
 778
 779 (ChordNames . "
 780     Typesets chord names.  Can contain @code{ChordNamesVoice}
 781     contexts.")
 782
 783 (Lyrics . "
 784     Typesets lyrics.  It can contain @code{LyricsVoice} contexts.
 785 ")
 786 (Staff . "
 787     Handles clefs, bar lines, keys, accidentals.  It can contain
 788     @code{Voice} contexts.
 789 ")
 790 (RhythmicStaff . "
 791     A context like @code{Staff} but for printing rhythms.  Pitches are
 792     ignored; the notes are printed on one line.  It can contain
 793     @code{Voice} contexts.
 794 ")
 795 (GrandStaff . "
 796     Contains @code{Staff} or @code{RhythmicStaff} contexts.  It adds a
 797     brace on the left side, grouping the staves together.  The bar
 798     lines of the contained staves are connected vertically.  It can
 799     contain @code{Staff} contexts.")
 800
 801 (PianoStaff . "
 802     Just like @code{GrandStaff} but with @code{minVerticalAlign} set
 803     equal to @code{maxVerticalAlign} so that interstaff beaming and
 804     slurring can be used.")
 805
 806 (StaffGroup . "
 807     Contains @code{Staff} or @code{RhythmicStaff} contexts.  Adds a
 808     bracket on the left side, grouping the staves together.  The bar
 809     lines of the contained staves are connected vertically.  It can
 810     contain @code{Staff}, @code{RhythmicStaff}, @code{GrandStaff}, or
 811     @code{Lyrics} contexts.
 812 ")
 813 (ChoirStaff . "
 814     Identical to @code{StaffGroup} except that the contained staves
 815     are not connected vertically.
 816 ")
 817 (Score . "
 818     This is the top level notation context.  No other context can
 819     contain a @code{Score} context.  This context handles the
 820     administration of time signatures.  It also makes sure that items
 821     such as clefs, time signatures, and key-signatures are aligned
 822     across staves.  It can contain @code{Lyrics}, @code{Staff},
 823     @code{RhythmicStaff}, @code{GrandStaff}, @code{StaffGroup}, and
 824     @code{ChoirStaff} contexts.
 825
 826     You cannot explicitly instantiate a Score context (since it is
 827     not contained in any other context).  It is instantiated
 828     automatically when an output definition (a @code{\score} or
 829     @code{\paper} block) is processed.
 830 ")
 831 )
 832 )
 833
 834 (set! context-description-alist
 835       (sort context-description-alist alist<?))
 836