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
103 'axis-group-interface
104 "a group of coupled grobs"
111 'note-column-interface
112 "Stem and noteheads combined"
125 beamed-minimum-lengths
157 extremity-offset-alist
167 'side-position-interface
168 "Position a victim object (this one) next to other objects (the support).
169 #'direction = where to put the victim object (left or right?)
175 side-relative-direction
186 'accidentals-interface
196 'line-of-score-interface
197 "Super grob, parent of all:
199 The columns of a score that form one line. The toplevel grob. Any
200 grob has a Line_of_score as both X and Y reference point. The
201 Paper_score contains one grob of this type. Control enters the
202 Grob dependency calculation from this single Line_of_score
205 between-system-string
207 before-line-breaking-callback
208 after-line-breaking-callback
217 '( style stem-attachment-function note-character ))
228 'rhythmic-head-interface
244 'tuplet-bracket-interface
245 "A bracket with a number in the middle, used for tuplets."
250 tuplet-bracket-visibility
251 tuplet-number-visibility
259 " Order grobs top to bottom/left to right/right to left etc."
273 "read by align-interface"
281 'break-aligned-interface
282 "Items that are aligned in prefatory matter"
291 'chord-name-interface
292 "generate a chord name"
293 '( pitches inversion bass))
297 'time-signature-interface
298 "A time signature, in different styles.
299 The following values for 'style are are recognized:
303 4/4 and 2/2 are typeset as C and struck C, respectively. All
304 other time signatures are written with two digits.
307 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
308 typeset with old-style mensuration marks. All other time
309 signatures are written with two digits.
312 All time signatures are typeset with a single
313 digit, e.g. 3/2 is written as 3. (Any symbol starting
314 with the digit @code{1} will do.)
316 @item @code{C}@var{M}@code{/}@var{N},
317 @code{old}@var{M}@code{/}@var{N} or
319 Tells LilyPond to use a specific symbol as time signature,
320 regardless of the actual time signature.
323 See also the test-file @file{input/test/time.ly}.
332 This is a request to print a special bar symbol. It replaces the
333 regular bar symbol with a special
334 symbol. The argument @var{bartype} is a string which specifies the
335 kind of bar to print. Options are @code{\":|\"}
336 @cindex \"|A@@@code{:|}
339 @cindex \"|B@@@code{|:}
341 @cindex \"|C@@@code{:|:}
344 @cindex \"|D@@@code{||}
346 @cindex \"|E@@@code{|.}
349 @cindex \"|F@@@code{.|}
351 @cindex \"|G@@@code{.|.}
354 These produce, respectively, a right repeat, a left repeat, a double
355 repeat, a double bar, a start bar, an end bar, and a thick double bar.
356 If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
357 but a line break is allowed at that spot.
360 '(bar-size-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function ))
367 padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
370 '( grow-direction thickness height padding
376 "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
377 '(stems arpeggio-direction))
382 'note-collision-interface
383 "An object that handles collisions between notes with different
384 stem directions and horizontal shifts. Most of the interesting
385 properties are to be set in @ref{note-column-interface}"
386 '(merge-differently-dotted note-width))
392 "A custos is a staff context symbol that appears at the end of a
393 staff line with monophonic musical contents (i.e. with a single
394 voice). It anticipates the pitch of the first note of the following
395 line and thus helps the player or singer to manage line breaks
396 during performance, thus enhancing readability of a score.
398 Custodes were frequently used in music notation until the 16th
399 century. There were different appearences for different notation
400 styles. Nowadays, they have survived only in special forms of
401 musical notation such as via the editio vaticana dating back to the
402 beginning of the 20th century.
404 [TODO: add to glossary]"
415 "The dots to go with a notehead/rest. A separate interface, since they
416 are a party in collision resolution.
417 #'direction is the Direction to handle staff-line collisions in."
418 '(direction dot-count))
423 "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
424 '(font-style font-series font-shape font-family font-name
425 font-design-size font-relative-size)
432 "A scheme markup text"
433 '(text align baseline-skip lookup raise kern magnify))
437 'dot-column-interface
438 "Interface that groups dots so they form a column"
445 "Any kind of loudness sign"
453 "A fingering instruction"
459 'separation-spanner-interface
460 "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
465 'text-script-interface
472 'grace-alignment-interface
473 "put grace notes in line"
481 'hara-kiri-group-interface
482 " As Vertical_group_spanner, but keep track of interesting items. If
483 we don't contain any interesting items after linebreaking, then
484 gracefully commit suicide. Objective: don't disgrace Lily by
485 typesetting empty lines in orchestral scores."
486 '( items-worth-living )
491 'line-spanner-interface
492 "Generic line drawn between two objects, eg. for use with glissandi.
493 gap is measured in staff-spaces. "
495 '(gap dash-period dash-length line-thickness type
500 'lyric-hyphen-interface
501 "A centred hyphen is a simple line between lyrics used to divide
502 syllables. The length of the hyphen line should stretch based on the
503 size of the gap between syllables."
505 '( thickness height minimum-length word-space
510 'key-signature-interface
511 "A group of accidentals."
520 'lyric-extender-interface
521 "The extender is a simple line at the baseline of the lyric
522 that helps show the length of a melissima (tied/slurred note)."
532 'lyric-syllable-interface
533 "a single piece of lyrics"
537 ignore-length-mismatch
552 'multi-measure-rest-interface
553 "A rest that spans a whole number of measures. For typesetting the
554 numbers, fields from font-interface may be used.
556 padding is the space between number and rest. Measured in staffspace.
559 '( columns expand-limit minimum-width padding))
563 'paper-column-interface
566 '(column-space-strength before-musical-spacing-factor
567 stem-spacing-correction before-grace-spacing-factor when bounded-by-me
568 dir-list shortest-playing-duration shortest-starter-duration
569 contains-grace extra-space stretch-distance ))
575 "A porrectus ligature, joining two note heads into a single grob."
581 'spaceable-element-interface
582 "An grob (generally a Paper_column) that takes part in the
592 'rest-collision-interface
593 "Move around ordinary rests (not multi-measure-rests) to avoid
611 'script-column-interface
612 "An interface that sorts scripts according to their @code{script-priority}"
618 'spacing-spanner-interface
619 " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
620 The space taken by a note is determined by the formula
624 where TIME is the amount of time a note occupies. The value of C is
625 chosen such that the smallest space within a measure is
626 arithmetic_basicspace:
628 C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
630 The smallest space is the one following the shortest note in the
631 measure, or the space following a hypothetical 1/8 note. Typically
632 arithmetic_basicspace is set to a value so that the shortest note
633 takes about two noteheads of space (ie, is followed by a notehead of
637 2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
639 @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
640 @{ assuming: SHORTEST <= 1/8 @}
642 = arithmetic_multiplier *
643 ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
645 = arithmetic_multiplier * arithmetic_basicspace
647 @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
649 = quartwidth * arithmetic_basicspace
653 arithmetic_basicspace = 2/1 = 2
656 If you want to space your music wider, use something like:
658 arithmetic_basicspace = 4.;
662 maximum-duration-for-spacing
663 arithmetic-basicspace
664 arithmetic-multiplier
670 'staff-symbol-referencer-interface
672 "Object whose Y position is meaning with reference to a staff
673 symbol. Objects that have this interface should include
674 Staff_symbol_referencer::callback in their Y-offset-callback.
683 'staff-symbol-interface
684 "This spanner draws the lines of a staff. The middle line is
694 'stem-tremolo-interface
696 '( stem beam-width beam-thickness beam-space-function
701 'separation-item-interface
702 "Item that computes widths to generate spacing rods.
704 Calc dimensions for the Separating_group_spanner; this has to be
705 an item to get dependencies correct. It can't be an grob_group
706 since these usually are in a different X_group
714 'sustain-pedal-interface
720 'system-start-delimiter-interface
721 "#'style can be bar-line, bracket or brace"
722 '(bar-line-collapse-height brace-collapse-height bracket-collapse-height
723 thickness arch-height arch-angle arch-thick
724 arch-width bracket-thick glyph ))
728 'text-spanner-interface
729 "generic text spanner"
742 "A tie connecting two noteheads.
743 direction = Forced direction for all ties"
760 'tie-column-interface
761 "that sets tie directions in a tied chord"
766 'percent-repeat-interface
767 "Repeats that look like percent signs"
771 'volta-bracket-interface
772 "Volta bracket with number"
782 "A bar line that spans other barlines (typically used to get cross-staff barlines."
787 (primitive-eval (cons
789 (map (lambda (x) (list 'define (car x) (list 'quote (cdr x))))
793 (define (interface-names) (map (lambda (x) (symbol->string (car x))) all-interfaces))