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
89 (define clef-interface
100 (define axis-group-interface
102 'axis-group-interface
103 "a group of coupled grobs"
108 (define note-column-interface
110 'note-column-interface
111 "Stem and noteheads combined"
118 (define stem-interface
125 beamed-minimum-lengths
132 default-neutral-direction
144 (define slur-interface
158 extremity-offset-alist
166 (define side-position-interface
168 'side-position-interface
169 "Position a victim object (this one) next to other objects (the support).
170 #'direction = where to put the victim object (left or right?)
176 side-relative-direction
185 (define accidentals-interface
187 'accidentals-interface
195 (define line-of-score-interface
197 'line-of-score-interface
198 "Super grob, parent of all:
200 The columns of a score that form one line. The toplevel grob. Any
201 grob has a Line_of_score as both X and Y reference point. The
202 Paper_score contains one grob of this type. Control enters the
203 Grob dependency calculation from this single Line_of_score
206 between-system-string
208 before-line-breaking-callback
209 after-line-breaking-callback
214 (define note-head-interface
223 (define note-name-interface
233 (define rhythmic-head-interface
235 'rhythmic-head-interface
243 (define rest-interface
249 (define tuplet-bracket-interface
251 'tuplet-bracket-interface
252 "A bracket with a number in the middle, used for tuplets."
258 tuplet-bracket-visibility
259 tuplet-number-visibility
265 (define align-interface
268 " Order grobs top to bottom/left to right/right to left etc."
279 (define aligned-interface
282 "read by align-interface"
288 (define break-aligned-interface
290 'break-aligned-interface
291 "Items that are aligned in prefatory matter"
298 (define chord-name-interface
300 'chord-name-interface
301 "generate a chord name"
302 '( pitches inversion bass)))
304 (define time-signature-interface
306 'time-signature-interface
307 "A time signature, in different styles.
308 The following values for 'style are are recognized:
312 4/4 and 2/2 are typeset as C and struck C, respectively. All
313 other time signatures are written with two digits.
316 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
317 typeset with old-style mensuration marks. All other time
318 signatures are written with two digits.
321 All time signatures are typeset with a single
322 digit, e.g. 3/2 is written as 3. (Any symbol starting
323 with the digit @code{1} will do.)
325 @item @code{C}@var{M}@code{/}@var{N},
326 @code{old}@var{M}@code{/}@var{N} or
328 Tells LilyPond to use a specific symbol as time signature,
329 regardless of the actual time signature.
332 See also the test-file @file{input/test/time.ly}.
336 (define bar-line-interface
341 This is a request to print a special bar symbol. It replaces the
342 regular bar symbol with a special
343 symbol. The argument @var{bartype} is a string which specifies the
344 kind of bar to print. Options are @code{\":|\"}
345 @cindex \"|A@@@code{:|}
348 @cindex \"|B@@@code{|:}
350 @cindex \"|C@@@code{:|:}
353 @cindex \"|D@@@code{||}
355 @cindex \"|E@@@code{|.}
358 @cindex \"|F@@@code{.|}
360 @cindex \"|G@@@code{.|.}
363 These produce, respectively, a right repeat, a left repeat, a double
364 repeat, a double bar, a start bar, an end bar, and a thick double bar.
365 If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
366 but a line break is allowed at that spot.
369 '( barsize-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function )))
371 (define hairpin-interface
376 padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
379 '( grow-direction thickness height padding )
382 (define arpeggio-interface
385 "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
390 (define note-collision-interface
392 'note-collision-interface
393 "An object that handles collisions between notes with different
394 stem directions and horizontal shifts. Most of the interesting
395 properties are to be set in @ref{note-column-interface}"
396 '(merge-differently-dotted note-width)
400 (define custos-interface
403 "A custos is a staff context symbol that appears at the end of a
404 staff line with monophonic musical contents (i.e. with a single
405 voice). It anticipates the pitch of the first note of the following
406 line and thus helps the player or singer to manage line breaks
407 during performance, thus enhancing readability of a score.
409 Custodes were frequently used in music notation until the 16th
410 century. There were different appearences for different notation
411 styles. Nowadays, they have survived only in special forms of
412 musical notation such as via the editio vaticana dating back to the
413 beginning of the 20th century.
415 [TODO: add to glossary]"
424 (define dot-interface
427 "The dots to go with a notehead/rest. A separate interface, since they
428 are a party in collision resolution.
429 #'direction is the Direction to handle staff-line collisions in."
430 '(direction dot-count)
434 (define font-interface
437 "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
438 '(font-style font-series font-shape font-family font-name
439 font-point-size font-relative-size)
443 (define text-interface
446 "A scheme markup text"
447 '(text align lookup raise kern magnify)))
449 (define dot-column-interface
451 'dot-column-interface
452 "Interface that groups dots so they form a column"
456 (define dynamic-interface
459 "Any kind of loudness sign"
464 (define finger-interface
467 "A fingering instruction"
471 (define separation-spanner-interface
473 'separation-spanner-interface
474 "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
477 (define text-script-interface
479 'text-script-interface
484 (define grace-alignment-interface
486 'grace-alignment-interface
487 "put grace notes in line"
493 (define hara-kiri-group-interface
495 'hara-kiri-group-interface
496 " As Vertical_group_spanner, but keep track of interesting items. If
497 we don't contain any interesting items after linebreaking, then
498 gracefully commit suicide. Objective: don't disgrace Lily by
499 typesetting empty lines in orchestral scores."
500 '( items-worth-living )
503 (define line-spanner-interface
505 'line-spanner-interface
506 "Generic line drawn between two objects, eg. for use with glissandi.
507 gap is measured in staff-spaces. "
509 '(gap dash-period dash-length line-thickness type )
512 (define lyric-hyphen-interface
514 'lyric-hyphen-interface
515 "A centred hyphen is a simple line between lyrics used to divide
516 syllables. The length of the hyphen line should stretch based on the
517 size of the gap between syllables."
519 '( thickness height minimum-length word-space )
522 (define key-signature-interface
524 'key-signature-interface
525 "A group of accidentals."
532 (define lyric-extender-interface
534 'lyric-extender-interface
535 "The extender is a simple line at the baseline of the lyric
536 that helps show the length of a melissima (tied/slurred note)."
544 (define lyric-syllable-interface
546 'lyric-syllable-interface
547 "a single piece of lyrics"
553 (define mark-interface
560 (define multi-measure-rest-interface
562 'multi-measure-rest-interface
563 "A rest that spans a whole number of measures. For typesetting the
564 numbers, fields from font-interface may be used.
566 padding is the space between number and rest. Measured in staffspace.
569 '( columns expand-limit minimum-width padding )
573 (define paper-column-interface
575 'paper-column-interface
578 '(column-space-strength before-musical-spacing-factor
579 stem-spacing-correction before-grace-spacing-factor when bounded-by-me
580 dir-list shortest-playing-duration shortest-starter-duration
581 contains-grace extra-space stretch-distance ))
585 (define spaceable-element-interface
587 'spaceable-element-interface
588 "An grob (generally a Paper_column) that takes part in the
596 (define rest-collision-interface
598 'rest-collision-interface
599 "Move around ordinary rests (not multi-measure-rests) to avoid
607 (define script-interface
615 (define script-column-interface
617 'script-column-interface
618 "An interface that sorts scripts according to their @code{script-priority}"
622 (define spacing-spanner-interface
624 'spacing-spanner-interface
625 " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
626 The space taken by a note is determined by the formula
630 where TIME is the amount of time a note occupies. The value of C is
631 chosen such that the smallest space within a measure is
632 arithmetic_basicspace:
634 C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
636 The smallest space is the one following the shortest note in the
637 measure, or the space following a hypothetical 1/8 note. Typically
638 arithmetic_basicspace is set to a value so that the shortest note
639 takes about two noteheads of space (ie, is followed by a notehead of
643 2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
645 @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
646 @{ assuming: SHORTEST <= 1/8 @}
648 = arithmetic_multiplier *
649 ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
651 = arithmetic_multiplier * arithmetic_basicspace
653 @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
655 = quartwidth * arithmetic_basicspace
659 arithmetic_basicspace = 2/1 = 2
662 If you want to space your music wider, use something like:
664 arithmetic_basicspace = 4.;
668 maximum-duration-for-spacing
669 arithmetic-basicspace
670 arithmetic-multiplier
674 (define staff-symbol-interface
676 'staff-symbol-interface
677 "This spanner draws the lines of a staff. The middle line is
684 (define stem-tremolo-interface
686 'stem-tremolo-interface
688 '( stem beam-width beam-thickness beam-space-function
691 (define separation-item-interface
693 'separation-item-interface
694 "Item that computes widths to generate spacing rods.
696 Calc dimensions for the Separating_group_spanner; this has to be
697 an item to get dependencies correct. It can't be an grob_group
698 since these usually are in a different X_group
704 (define sustain-pedal-interface
706 'sustain-pedal-interface
710 (define system-start-delimiter-interface
712 'system-start-delimiter-interface
713 "#'style can be bar-line, bracket or brace"
714 '(thickness arch-height arch-angle arch-thick
715 arch-width bracket-thick glyph )))
717 (define text-spanner-interface
719 'text-spanner-interface
720 "generic text spanner"
731 (define tie-interface
734 "A tie connecting two noteheads.
735 direction = Forced direction for all ties"
750 (define tie-column-interface
752 'tie-column-interface
753 "that sets tie directions in a tied chord"
757 (define volta-bracket-interface
759 'volta-bracket-interface
760 "Volta bracket with number"
767 (define span-bar-interface
770 "A bar line that spans other barlines (typically used to get cross-staff barlines."
774 ;(define urg-miss-last-interface )