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 name . interfaces)
28 (let* ((ifs (cons general-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.
36 (cons 'interfaces syms)
37 (cons 'interface-descriptions ifs)
38 ; (cons 'interface-descriptions (cadr merged))
39 ;; description of the grob itself?
40 ; (cons 'properties prop-typep-pairs)
45 'general-grob-interface
46 "All grobs support this"
71 #'thickness= weight of beams, in staffspace
78 default-neutral-direction
83 vertical-position-quant-function
85 outer-stem-length-limit
104 'axis-group-interface
105 "a group of coupled grobs"
112 'note-column-interface
113 "Stem and noteheads combined"
126 beamed-minimum-lengths
133 default-neutral-direction
159 extremity-offset-alist
169 'side-position-interface
170 "Position a victim object (this one) next to other objects (the support).
171 #'direction = where to put the victim object (left or right?)
177 side-relative-direction
188 'accidentals-interface
198 'line-of-score-interface
199 "Super grob, parent of all:
201 The columns of a score that form one line. The toplevel grob. Any
202 grob has a Line_of_score as both X and Y reference point. The
203 Paper_score contains one grob of this type. Control enters the
204 Grob dependency calculation from this single Line_of_score
207 between-system-string
209 before-line-breaking-callback
210 after-line-breaking-callback
220 style attachment-slope note-character
234 'rhythmic-head-interface
250 'tuplet-bracket-interface
251 "A bracket with a number in the middle, used for tuplets."
257 tuplet-bracket-visibility
258 tuplet-number-visibility
266 " Order grobs top to bottom/left to right/right to left etc."
280 "read by align-interface"
288 'break-aligned-interface
289 "Items that are aligned in prefatory matter"
298 'chord-name-interface
299 "generate a chord name"
300 '( pitches inversion bass))
304 'time-signature-interface
305 "A time signature, in different styles.
306 The following values for 'style are are recognized:
310 4/4 and 2/2 are typeset as C and struck C, respectively. All
311 other time signatures are written with two digits.
314 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
315 typeset with old-style mensuration marks. All other time
316 signatures are written with two digits.
319 All time signatures are typeset with a single
320 digit, e.g. 3/2 is written as 3. (Any symbol starting
321 with the digit @code{1} will do.)
323 @item @code{C}@var{M}@code{/}@var{N},
324 @code{old}@var{M}@code{/}@var{N} or
326 Tells LilyPond to use a specific symbol as time signature,
327 regardless of the actual time signature.
330 See also the test-file @file{input/test/time.ly}.
339 This is a request to print a special bar symbol. It replaces the
340 regular bar symbol with a special
341 symbol. The argument @var{bartype} is a string which specifies the
342 kind of bar to print. Options are @code{\":|\"}
343 @cindex \"|A@@@code{:|}
346 @cindex \"|B@@@code{|:}
348 @cindex \"|C@@@code{:|:}
351 @cindex \"|D@@@code{||}
353 @cindex \"|E@@@code{|.}
356 @cindex \"|F@@@code{.|}
358 @cindex \"|G@@@code{.|.}
361 These produce, respectively, a right repeat, a left repeat, a double
362 repeat, a double bar, a start bar, an end bar, and a thick double bar.
363 If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
364 but a line break is allowed at that spot.
367 '( barsize-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function ))
374 padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
377 '( grow-direction thickness height padding
383 "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
389 'note-collision-interface
390 "An object that handles collisions between notes with different
391 stem directions and horizontal shifts. Most of the interesting
392 properties are to be set in @ref{note-column-interface}"
393 '(merge-differently-dotted note-width))
399 "A custos is a staff context symbol that appears at the end of a
400 staff line with monophonic musical contents (i.e. with a single
401 voice). It anticipates the pitch of the first note of the following
402 line and thus helps the player or singer to manage line breaks
403 during performance, thus enhancing readability of a score.
405 Custodes were frequently used in music notation until the 16th
406 century. There were different appearences for different notation
407 styles. Nowadays, they have survived only in special forms of
408 musical notation such as via the editio vaticana dating back to the
409 beginning of the 20th century.
411 [TODO: add to glossary]"
422 "The dots to go with a notehead/rest. A separate interface, since they
423 are a party in collision resolution.
424 #'direction is the Direction to handle staff-line collisions in."
425 '(direction dot-count))
430 "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
431 '(font-style font-series font-shape font-family font-name
432 font-design-size font-relative-size)
439 "A scheme markup text"
440 '(text align baseline-skip lookup raise kern magnify))
444 'dot-column-interface
445 "Interface that groups dots so they form a column"
452 "Any kind of loudness sign"
460 "A fingering instruction"
466 'separation-spanner-interface
467 "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
472 'text-script-interface
479 'grace-alignment-interface
480 "put grace notes in line"
488 'hara-kiri-group-interface
489 " As Vertical_group_spanner, but keep track of interesting items. If
490 we don't contain any interesting items after linebreaking, then
491 gracefully commit suicide. Objective: don't disgrace Lily by
492 typesetting empty lines in orchestral scores."
493 '( items-worth-living )
498 'line-spanner-interface
499 "Generic line drawn between two objects, eg. for use with glissandi.
500 gap is measured in staff-spaces. "
502 '(gap dash-period dash-length line-thickness type
507 'lyric-hyphen-interface
508 "A centred hyphen is a simple line between lyrics used to divide
509 syllables. The length of the hyphen line should stretch based on the
510 size of the gap between syllables."
512 '( thickness height minimum-length word-space
517 'key-signature-interface
518 "A group of accidentals."
527 'lyric-extender-interface
528 "The extender is a simple line at the baseline of the lyric
529 that helps show the length of a melissima (tied/slurred note)."
539 'lyric-syllable-interface
540 "a single piece of lyrics"
555 'multi-measure-rest-interface
556 "A rest that spans a whole number of measures. For typesetting the
557 numbers, fields from font-interface may be used.
559 padding is the space between number and rest. Measured in staffspace.
562 '( columns expand-limit minimum-width padding))
566 'paper-column-interface
569 '(column-space-strength before-musical-spacing-factor
570 stem-spacing-correction before-grace-spacing-factor when bounded-by-me
571 dir-list shortest-playing-duration shortest-starter-duration
572 contains-grace extra-space stretch-distance ))
577 'spaceable-element-interface
578 "An grob (generally a Paper_column) that takes part in the
588 'rest-collision-interface
589 "Move around ordinary rests (not multi-measure-rests) to avoid
607 'script-column-interface
608 "An interface that sorts scripts according to their @code{script-priority}"
614 'spacing-spanner-interface
615 " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
616 The space taken by a note is determined by the formula
620 where TIME is the amount of time a note occupies. The value of C is
621 chosen such that the smallest space within a measure is
622 arithmetic_basicspace:
624 C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
626 The smallest space is the one following the shortest note in the
627 measure, or the space following a hypothetical 1/8 note. Typically
628 arithmetic_basicspace is set to a value so that the shortest note
629 takes about two noteheads of space (ie, is followed by a notehead of
633 2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
635 @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
636 @{ assuming: SHORTEST <= 1/8 @}
638 = arithmetic_multiplier *
639 ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
641 = arithmetic_multiplier * arithmetic_basicspace
643 @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
645 = quartwidth * arithmetic_basicspace
649 arithmetic_basicspace = 2/1 = 2
652 If you want to space your music wider, use something like:
654 arithmetic_basicspace = 4.;
658 maximum-duration-for-spacing
659 arithmetic-basicspace
660 arithmetic-multiplier
666 'staff-symbol-referencer-interface
668 "Object whose Y position is meaning with reference to a staff
669 symbol. Objects that have this interface should include
670 Staff_symbol_referencer::callback in their Y-offset-callback.
679 'staff-symbol-interface
680 "This spanner draws the lines of a staff. The middle line is
690 'stem-tremolo-interface
692 '( stem beam-width beam-thickness beam-space-function
697 'separation-item-interface
698 "Item that computes widths to generate spacing rods.
700 Calc dimensions for the Separating_group_spanner; this has to be
701 an item to get dependencies correct. It can't be an grob_group
702 since these usually are in a different X_group
710 'sustain-pedal-interface
716 'system-start-delimiter-interface
717 "#'style can be bar-line, bracket or brace"
718 '(bar-line-collapse-height brace-collapse-height bracket-collapse-height
719 thickness arch-height arch-angle arch-thick
720 arch-width bracket-thick glyph ))
724 'text-spanner-interface
725 "generic text spanner"
738 "A tie connecting two noteheads.
739 direction = Forced direction for all ties"
756 'tie-column-interface
757 "that sets tie directions in a tied chord"
762 'percent-repeat-interface
763 "Repeats that look like percent signs"
767 'volta-bracket-interface
768 "Volta bracket with number"
778 "A bar line that spans other barlines (typically used to get cross-staff barlines."
785 (map (lambda (x) (list 'define (car x) (list 'quote (cdr x))))
789 (define (interface-names) (map (lambda (x) (symbol->string (car x))) all-interfaces))