1 ;;;; interface-description.scm -- part of generated backend documentation
3 ;;;; source file of the GNU LilyPond music typesetter
5 ;;;; (c) 1998--2001 Han-Wen Nienhuys <hanwen@cs.uu.nl>
6 ;;;; Jan Nieuwenhuizen <janneke@gnu.org>
9 ; should include default value?
13 ;;; Score elements are called `objects' now and then, which gets
14 ;;; rather confusing, we now have `elements', `items', `spanners'
18 (define all-interfaces '())
20 (define (lily-interface symbol description props)
21 (set! all-interfaces (acons symbol (list symbol
23 props) all-interfaces)
27 (define (grob-description . interfaces)
28 (let* ((ifs (cons grob-interface interfaces))
29 (props (map caddr ifs))
30 ; (prop-typep-pairs (map (lambda (x) (cons (car x) (cadr x)))
31 ; (apply append props)))
34 (list (cons 'separator "\n\n\n") ;easy printing.
35 (cons 'interfaces syms)
36 (cons 'interface-descriptions ifs)
37 ; (cons 'interface-descriptions (cadr merged))
38 ;; description of the grob itself?
39 ; (cons 'properties prop-typep-pairs)
45 "All grobs support this"
70 #'thickness= weight of beams, in staffspace
82 vertical-position-quant-function
84 outer-stem-length-limit
91 'staff-spacing-interface
97 'note-spacing-interface
114 'axis-group-interface
115 "a group of coupled grobs"
122 'note-column-interface
123 "Stem and noteheads combined"
136 beamed-minimum-lengths
168 extremity-offset-alist
178 'side-position-interface
179 "Position a victim object (this one) next to other objects (the support).
180 #'direction = where to put the victim object (left or right?)
186 side-relative-direction
197 'accidentals-interface
209 'line-of-score-interface
210 "Super grob, parent of all:
212 The columns of a score that form one line. The toplevel grob. Any
213 grob has a Line_of_score as both X and Y reference point. The
214 Paper_score contains one grob of this type. Control enters the
215 Grob dependency calculation from this single Line_of_score
218 between-system-string
220 before-line-breaking-callback
221 after-line-breaking-callback
230 '( style stem-attachment-function note-character ))
241 'rhythmic-head-interface
257 'tuplet-bracket-interface
258 "A bracket with a number in the middle, used for tuplets."
263 tuplet-bracket-visibility
264 tuplet-number-visibility
272 " Order grobs top to bottom/left to right/right to left etc."
286 "read by align-interface"
294 'break-aligned-interface
295 "Items that are aligned in prefatory matter"
304 'chord-name-interface
305 "generate a chord name"
306 '( pitches inversion bass))
310 'time-signature-interface
311 "A time signature, in different styles.
312 The following values for 'style are are recognized:
316 4/4 and 2/2 are typeset as C and struck C, respectively. All
317 other time signatures are written with two digits.
320 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
321 typeset with old-style mensuration marks. All other time
322 signatures are written with two digits.
325 All time signatures are typeset with a single
326 digit, e.g. 3/2 is written as 3. (Any symbol starting
327 with the digit @code{1} will do.)
329 @item @code{C}@var{M}@code{/}@var{N},
330 @code{old}@var{M}@code{/}@var{N} or
332 Tells LilyPond to use a specific symbol as time signature,
333 regardless of the actual time signature.
336 See also the test-file @file{input/test/time.ly}.
345 This is a request to print a special bar symbol. It replaces the
346 regular bar symbol with a special
347 symbol. The argument @var{bartype} is a string which specifies the
348 kind of bar to print. Options are @code{\":|\"}
349 @cindex \"|A@@@code{:|}
352 @cindex \"|B@@@code{|:}
354 @cindex \"|C@@@code{:|:}
357 @cindex \"|D@@@code{||}
359 @cindex \"|E@@@code{|.}
362 @cindex \"|F@@@code{.|}
364 @cindex \"|G@@@code{.|.}
367 These produce, respectively, a right repeat, a left repeat, a double
368 repeat, a double bar, a start bar, an end bar, and a thick double bar.
369 If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
370 but a line break is allowed at that spot.
373 '(bar-size-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function ))
380 padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
383 '( grow-direction thickness height padding
389 "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
390 '(stems arpeggio-direction))
395 'note-collision-interface
396 "An object that handles collisions between notes with different
397 stem directions and horizontal shifts. Most of the interesting
398 properties are to be set in @ref{note-column-interface}"
399 '(merge-differently-dotted note-width))
405 "A custos is a staff context symbol that appears at the end of a
406 staff line with monophonic musical contents (i.e. with a single
407 voice). It anticipates the pitch of the first note of the following
408 line and thus helps the player or singer to manage line breaks
409 during performance, thus enhancing readability of a score.
411 Custodes were frequently used in music notation until the 16th
412 century. There were different appearences for different notation
413 styles. Nowadays, they have survived only in special forms of
414 musical notation such as via the editio vaticana dating back to the
415 beginning of the 20th century.
417 [TODO: add to glossary]"
428 "The dots to go with a notehead/rest. A separate interface, since they
429 are a party in collision resolution.
430 #'direction is the Direction to handle staff-line collisions in."
431 '(direction dot-count))
436 "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
437 '(font-style font-series font-shape font-family font-name
438 font-design-size font-relative-size)
445 "A scheme markup text"
446 '(text align baseline-skip lookup raise kern magnify))
450 'dot-column-interface
451 "Interface that groups dots so they form a column"
458 "Any kind of loudness sign"
466 "A fingering instruction"
472 'separation-spanner-interface
473 "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
478 'text-script-interface
485 'grace-alignment-interface
486 "put grace notes in line"
494 'hara-kiri-group-interface
495 " As Vertical_group_spanner, but keep track of interesting items. If
496 we don't contain any interesting items after linebreaking, then
497 gracefully commit suicide. Objective: don't disgrace Lily by
498 typesetting empty lines in orchestral scores."
499 '( items-worth-living )
504 'line-spanner-interface
505 "Generic line drawn between two objects, eg. for use with glissandi.
506 gap is measured in staff-spaces. "
508 '(gap dash-period dash-length line-thickness type
513 'lyric-hyphen-interface
514 "A centred hyphen is a simple line between lyrics used to divide
515 syllables. The length of the hyphen line should stretch based on the
516 size of the gap between syllables."
518 '( thickness height minimum-length word-space
523 'key-signature-interface
524 "A group of accidentals."
533 'lyric-extender-interface
534 "The extender is a simple line at the baseline of the lyric
535 that helps show the length of a melissima (tied/slurred note)."
545 'lyric-syllable-interface
546 "a single piece of lyrics"
550 ignore-length-mismatch
565 'multi-measure-rest-interface
566 "A rest that spans a whole number of measures. For typesetting the
567 numbers, fields from font-interface may be used.
569 padding is the space between number and rest. Measured in staffspace.
572 '( columns expand-limit minimum-width padding))
576 'paper-column-interface
579 '(column-space-strength before-musical-spacing-factor
580 stem-spacing-correction before-grace-spacing-factor when bounded-by-me
581 dir-list shortest-playing-duration shortest-starter-duration
582 contains-grace extra-space stretch-distance ))
588 "A porrectus ligature, joining two note heads into a single grob."
594 'spaceable-element-interface
595 "An grob (generally a Paper_column) that takes part in the
605 'rest-collision-interface
606 "Move around ordinary rests (not multi-measure-rests) to avoid
624 'script-column-interface
625 "An interface that sorts scripts according to their @code{script-priority}"
631 'spacing-spanner-interface
632 " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
633 The space taken by a note is determined by the formula
637 where TIME is the amount of time a note occupies. The value of C is
638 chosen such that the smallest space within a measure is
639 arithmetic_basicspace:
641 C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
643 The smallest space is the one following the shortest note in the
644 measure, or the space following a hypothetical 1/8 note. Typically
645 arithmetic_basicspace is set to a value so that the shortest note
646 takes about two noteheads of space (ie, is followed by a notehead of
650 2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
652 @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
653 @{ assuming: SHORTEST <= 1/8 @}
655 = arithmetic_multiplier *
656 ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
658 = arithmetic_multiplier * arithmetic_basicspace
660 @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
662 = quartwidth * arithmetic_basicspace
666 arithmetic_basicspace = 2/1 = 2
669 If you want to space your music wider, use something like:
671 arithmetic_basicspace = 4.;
675 maximum-duration-for-spacing
676 arithmetic-basicspace
677 arithmetic-multiplier
683 'staff-symbol-referencer-interface
685 "Object whose Y position is meaning with reference to a staff
686 symbol. Objects that have this interface should include
687 Staff_symbol_referencer::callback in their Y-offset-callback.
696 'staff-symbol-interface
697 "This spanner draws the lines of a staff. The middle line is
707 'stem-tremolo-interface
709 '( stem beam-width beam-thickness beam-space-function
714 'separation-item-interface
715 "Item that computes widths to generate spacing rods.
717 Calc dimensions for the Separating_group_spanner; this has to be
718 an item to get dependencies correct. It can't be an grob_group
719 since these usually are in a different X_group
727 'sustain-pedal-interface
733 'system-start-delimiter-interface
734 "#'style can be bar-line, bracket or brace"
735 '(bar-line-collapse-height brace-collapse-height bracket-collapse-height
736 thickness arch-height arch-angle arch-thick
737 arch-width bracket-thick glyph ))
741 'text-spanner-interface
742 "generic text spanner"
755 "A tie connecting two noteheads.
756 direction = Forced direction for all ties"
773 'tie-column-interface
774 "that sets tie directions in a tied chord"
779 'percent-repeat-interface
780 "Repeats that look like percent signs"
784 'volta-bracket-interface
785 "Volta bracket with number"
795 "A bar line that spans other barlines (typically used to get cross-staff barlines."
800 (primitive-eval (cons
802 (map (lambda (x) (list 'define (car x) (list 'quote (cdr x))))
806 (define (interface-names) (map (lambda (x) (symbol->string (car x))) all-interfaces))