1 ;;;; interface-description.scm -- part of generated backend documentation
3 ;;;; source file of the GNU LilyPond music typesetter
5 ;;;; (c) 1998--2000 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 (lily-interface symbol description props)
26 (define (grob-description name . interfaces)
27 (let* ((ifs (cons general-grob-interface interfaces))
28 (props (map caddr ifs))
29 ; (prop-typep-pairs (map (lambda (x) (cons (car x) (cadr x)))
30 ; (apply append props)))
33 (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)
42 (define general-grob-interface
44 'general-grob-interface
45 "All grobs support this"
65 (define beam-interface
70 #'thickness= weight of beams, in staffspace
77 default-neutral-direction
82 vertical-position-quant-function
84 outer-stem-length-limit
90 (define clef-interface
101 (define axis-group-interface
103 'axis-group-interface
104 "a group of coupled grobs"
109 (define note-column-interface
111 'note-column-interface
112 "Stem and noteheads combined"
119 (define stem-interface
126 beamed-minimum-lengths
133 default-neutral-direction
145 (define slur-interface
159 extremity-offset-alist
167 (define side-position-interface
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
186 (define accidentals-interface
188 'accidentals-interface
196 (define line-of-score-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
215 (define note-head-interface
224 (define note-name-interface
234 (define rhythmic-head-interface
236 'rhythmic-head-interface
244 (define rest-interface
250 (define tuplet-bracket-interface
252 'tuplet-bracket-interface
253 "A bracket with a number in the middle, used for tuplets."
259 tuplet-bracket-visibility
260 tuplet-number-visibility
266 (define align-interface
269 " Order grobs top to bottom/left to right/right to left etc."
280 (define aligned-interface
283 "read by align-interface"
289 (define break-aligned-interface
291 'break-aligned-interface
292 "Items that are aligned in prefatory matter"
299 (define chord-name-interface
301 'chord-name-interface
302 "generate a chord name"
303 '( pitches inversion bass)))
305 (define time-signature-interface
307 'time-signature-interface
308 "A time signature, in different styles.
309 The following values for 'style are are recognized:
313 4/4 and 2/2 are typeset as C and struck C, respectively. All
314 other time signatures are written with two digits.
317 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
318 typeset with old-style mensuration marks. All other time
319 signatures are written with two digits.
322 All time signatures are typeset with a single
323 digit, e.g. 3/2 is written as 3. (Any symbol starting
324 with the digit @code{1} will do.)
326 @item @code{C}@var{M}@code{/}@var{N},
327 @code{old}@var{M}@code{/}@var{N} or
329 Tells LilyPond to use a specific symbol as time signature,
330 regardless of the actual time signature.
333 See also the test-file @file{input/test/time.ly}.
337 (define bar-line-interface
342 This is a request to print a special bar symbol. It replaces the
343 regular bar symbol with a special
344 symbol. The argument @var{bartype} is a string which specifies the
345 kind of bar to print. Options are @code{\":|\"}
346 @cindex \"|A@@@code{:|}
349 @cindex \"|B@@@code{|:}
351 @cindex \"|C@@@code{:|:}
354 @cindex \"|D@@@code{||}
356 @cindex \"|E@@@code{|.}
359 @cindex \"|F@@@code{.|}
361 @cindex \"|G@@@code{.|.}
364 These produce, respectively, a right repeat, a left repeat, a double
365 repeat, a double bar, a start bar, an end bar, and a thick double bar.
366 If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
367 but a line break is allowed at that spot.
370 '( barsize-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function )))
372 (define hairpin-interface
377 padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
380 '( grow-direction thickness height padding )
383 (define arpeggio-interface
386 "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
391 (define note-collision-interface
393 'note-collision-interface
394 "An object that handles collisions between notes with different
395 stem directions and horizontal shifts. Most of the interesting
396 properties are to be set in @ref{note-column-interface}"
397 '(merge-differently-dotted note-width)
401 (define custos-interface
404 "A custos is a staff context symbol that appears at the end of a
405 staff line with monophonic musical contents (i.e. with a single
406 voice). It anticipates the pitch of the first note of the following
407 line and thus helps the player or singer to manage line breaks
408 during performance, thus enhancing readability of a score.
410 Custodes were frequently used in music notation until the 16th
411 century. There were different appearences for different notation
412 styles. Nowadays, they have survived only in special forms of
413 musical notation such as via the editio vaticana dating back to the
414 beginning of the 20th century.
416 [TODO: add to glossary]"
425 (define dot-interface
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)
435 (define font-interface
438 "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
439 '(font-style font-series font-shape font-family font-name
440 font-point-size font-relative-size)
444 (define text-interface
447 "A scheme markup text"
448 '(text align baseline-skip lookup raise kern magnify)))
450 (define dot-column-interface
452 'dot-column-interface
453 "Interface that groups dots so they form a column"
457 (define dynamic-interface
460 "Any kind of loudness sign"
465 (define finger-interface
468 "A fingering instruction"
472 (define separation-spanner-interface
474 'separation-spanner-interface
475 "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
478 (define text-script-interface
480 'text-script-interface
485 (define grace-alignment-interface
487 'grace-alignment-interface
488 "put grace notes in line"
494 (define hara-kiri-group-interface
496 'hara-kiri-group-interface
497 " As Vertical_group_spanner, but keep track of interesting items. If
498 we don't contain any interesting items after linebreaking, then
499 gracefully commit suicide. Objective: don't disgrace Lily by
500 typesetting empty lines in orchestral scores."
501 '( items-worth-living )
504 (define line-spanner-interface
506 'line-spanner-interface
507 "Generic line drawn between two objects, eg. for use with glissandi.
508 gap is measured in staff-spaces. "
510 '(gap dash-period dash-length line-thickness type )
513 (define lyric-hyphen-interface
515 'lyric-hyphen-interface
516 "A centred hyphen is a simple line between lyrics used to divide
517 syllables. The length of the hyphen line should stretch based on the
518 size of the gap between syllables."
520 '( thickness height minimum-length word-space )
523 (define key-signature-interface
525 'key-signature-interface
526 "A group of accidentals."
533 (define lyric-extender-interface
535 'lyric-extender-interface
536 "The extender is a simple line at the baseline of the lyric
537 that helps show the length of a melissima (tied/slurred note)."
545 (define lyric-syllable-interface
547 'lyric-syllable-interface
548 "a single piece of lyrics"
554 (define mark-interface
561 (define multi-measure-rest-interface
563 'multi-measure-rest-interface
564 "A rest that spans a whole number of measures. For typesetting the
565 numbers, fields from font-interface may be used.
567 padding is the space between number and rest. Measured in staffspace.
570 '( columns expand-limit minimum-width padding )
574 (define paper-column-interface
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 ))
586 (define spaceable-element-interface
588 'spaceable-element-interface
589 "An grob (generally a Paper_column) that takes part in the
597 (define rest-collision-interface
599 'rest-collision-interface
600 "Move around ordinary rests (not multi-measure-rests) to avoid
608 (define script-interface
616 (define script-column-interface
618 'script-column-interface
619 "An interface that sorts scripts according to their @code{script-priority}"
623 (define spacing-spanner-interface
625 'spacing-spanner-interface
626 " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
627 The space taken by a note is determined by the formula
631 where TIME is the amount of time a note occupies. The value of C is
632 chosen such that the smallest space within a measure is
633 arithmetic_basicspace:
635 C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
637 The smallest space is the one following the shortest note in the
638 measure, or the space following a hypothetical 1/8 note. Typically
639 arithmetic_basicspace is set to a value so that the shortest note
640 takes about two noteheads of space (ie, is followed by a notehead of
644 2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
646 @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
647 @{ assuming: SHORTEST <= 1/8 @}
649 = arithmetic_multiplier *
650 ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
652 = arithmetic_multiplier * arithmetic_basicspace
654 @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
656 = quartwidth * arithmetic_basicspace
660 arithmetic_basicspace = 2/1 = 2
663 If you want to space your music wider, use something like:
665 arithmetic_basicspace = 4.;
669 maximum-duration-for-spacing
670 arithmetic-basicspace
671 arithmetic-multiplier
675 (define staff-symbol-interface
677 'staff-symbol-interface
678 "This spanner draws the lines of a staff. The middle line is
686 (define stem-tremolo-interface
688 'stem-tremolo-interface
690 '( stem beam-width beam-thickness beam-space-function
693 (define separation-item-interface
695 'separation-item-interface
696 "Item that computes widths to generate spacing rods.
698 Calc dimensions for the Separating_group_spanner; this has to be
699 an item to get dependencies correct. It can't be an grob_group
700 since these usually are in a different X_group
706 (define sustain-pedal-interface
708 'sustain-pedal-interface
712 (define system-start-delimiter-interface
714 'system-start-delimiter-interface
715 "#'style can be bar-line, bracket or brace"
716 '(bar-line-collapse-height brace-collapse-height bracket-collapse-height
717 thickness arch-height arch-angle arch-thick
718 arch-width bracket-thick glyph )))
720 (define text-spanner-interface
722 'text-spanner-interface
723 "generic text spanner"
734 (define tie-interface
737 "A tie connecting two noteheads.
738 direction = Forced direction for all ties"
753 (define tie-column-interface
755 'tie-column-interface
756 "that sets tie directions in a tied chord"
760 (define volta-bracket-interface
762 'volta-bracket-interface
763 "Volta bracket with number"
770 (define span-bar-interface
773 "A bar line that spans other barlines (typically used to get cross-staff barlines."
777 ;(define urg-miss-last-interface )