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 ;;; TODO: this should be done through C++ macros, in order to have
19 ;;; tighter coupling between the C++ and its doco.
21 (define all-interfaces '())
23 (define (lily-interface symbol description props)
24 (set! all-interfaces (acons symbol (list symbol
26 props) all-interfaces)
30 (define (grob-description . interfaces)
31 (let* ((ifs (cons grob-interface interfaces))
32 (props (map caddr ifs))
33 ; (prop-typep-pairs (map (lambda (x) (cons (car x) (cadr x)))
34 ; (apply append props)))
37 (list (cons 'separator "\n\n\n") ;easy printing.
38 (cons 'interfaces syms)
39 (cons 'interface-descriptions ifs)
40 ; (cons 'interface-descriptions (cadr merged))
41 ;; description of the grob itself?
42 ; (cons 'properties prop-typep-pairs)
48 "All grobs support this"
73 #'thickness= weight of beams, in staffspace
85 vertical-position-quant-function
87 outer-stem-length-limit
94 'staff-spacing-interface
100 'note-spacing-interface
117 'axis-group-interface
118 "a group of coupled grobs"
125 'note-column-interface
126 "Stem and noteheads combined"
140 beamed-minimum-lengths
172 extremity-offset-alist
182 'side-position-interface
183 "Position a victim object (this one) next to other objects (the support).
184 #'direction = where to put the victim object (left or right?)
187 side-support-elements
190 side-relative-direction
201 'accidentals-interface
213 'line-of-score-interface
214 "Super grob, parent of all:
216 The columns of a score that form one line. The toplevel grob. Any
217 grob has a Line_of_score as both X and Y reference point. The
218 Paper_score contains one grob of this type. Control enters the
219 Grob dependency calculation from this single Line_of_score
222 between-system-string
224 before-line-breaking-callback
225 after-line-breaking-callback
234 '( style stem-attachment-function ))
245 'rhythmic-head-interface
261 'tuplet-bracket-interface
262 "A bracket with a number in the middle, used for tuplets."
267 tuplet-bracket-visibility
268 tuplet-number-visibility
276 " Order grobs top to bottom/left to right/right to left etc."
290 "read by align-interface"
298 'break-aligned-interface
299 "Items that are aligned in prefatory matter"
308 'chord-name-interface
309 "generate a chord name"
310 '( pitches inversion bass))
314 'time-signature-interface
315 "A time signature, in different styles.
316 The following values for 'style are are recognized:
320 4/4 and 2/2 are typeset as C and struck C, respectively. All
321 other time signatures are written with two digits.
324 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
325 typeset with old-style mensuration marks. All other time
326 signatures are written with two digits.
329 All time signatures are typeset with a single
330 digit, e.g. 3/2 is written as 3. (Any symbol starting
331 with the digit @code{1} will do.)
333 @item @code{C}@var{M}@code{/}@var{N},
334 @code{old}@var{M}@code{/}@var{N} or
336 Tells LilyPond to use a specific symbol as time signature,
337 regardless of the actual time signature.
340 See also the test-file @file{input/test/time.ly}.
349 This is a request to print a special bar symbol. It replaces the
350 regular bar symbol with a special
351 symbol. The argument @var{bartype} is a string which specifies the
352 kind of bar to print. Options are @code{\":|\"}
353 @cindex \"|A@@@code{:|}
356 @cindex \"|B@@@code{|:}
358 @cindex \"|C@@@code{:|:}
361 @cindex \"|D@@@code{||}
363 @cindex \"|E@@@code{|.}
366 @cindex \"|F@@@code{.|}
368 @cindex \"|G@@@code{.|.}
371 These produce, respectively, a right repeat, a left repeat, a double
372 repeat, a double bar, a start bar, an end bar, and a thick double bar.
373 If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
374 but a line break is allowed at that spot.
377 '(bar-size-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function ))
384 padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
387 '( grow-direction thickness height padding
393 "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
394 '(stems arpeggio-direction))
399 'note-collision-interface
400 "An object that handles collisions between notes with different
401 stem directions and horizontal shifts. Most of the interesting
402 properties are to be set in @ref{note-column-interface}"
403 '(merge-differently-dotted note-width))
409 "A custos is a staff context symbol that appears at the end of a
410 staff line with monophonic musical contents (i.e. with a single
411 voice). It anticipates the pitch of the first note of the following
412 line and thus helps the player or singer to manage line breaks
413 during performance, thus enhancing readability of a score.
415 Custodes were frequently used in music notation until the 16th
416 century. There were different appearences for different notation
417 styles. Nowadays, they have survived only in special forms of
418 musical notation such as via the editio vaticana dating back to the
419 beginning of the 20th century.
421 [TODO: add to glossary]"
432 "The dots to go with a notehead/rest. A separate interface, since they
433 are a party in collision resolution.
434 #'direction is the Direction to handle staff-line collisions in."
435 '(direction dot-count))
440 "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
441 '(font-style font-series font-shape font-family font-name
442 font-design-size font-relative-size)
449 "A scheme markup text"
450 '(text align baseline-skip lookup raise kern magnify))
454 'dot-column-interface
455 "Interface that groups dots so they form a column"
462 "Any kind of loudness sign"
470 "A fingering instruction"
476 'separation-spanner-interface
477 "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
482 'text-script-interface
489 'grace-alignment-interface
490 "put grace notes in line"
498 'hara-kiri-group-interface
499 " As Vertical_group_spanner, but keep track of interesting items. If
500 we don't contain any interesting items after linebreaking, then
501 gracefully commit suicide. Objective: don't disgrace Lily by
502 typesetting empty lines in orchestral scores."
503 '( items-worth-living )
508 'line-spanner-interface
509 "Generic line drawn between two objects, eg. for use with glissandi.
510 gap is measured in staff-spaces. "
512 '(gap dash-period dash-length line-thickness type
517 'lyric-hyphen-interface
518 "A centred hyphen is a simple line between lyrics used to divide
519 syllables. The length of the hyphen line should stretch based on the
520 size of the gap between syllables."
522 '( thickness height minimum-length word-space
527 'key-signature-interface
528 "A group of accidentals."
537 'lyric-extender-interface
538 "The extender is a simple line at the baseline of the lyric
539 that helps show the length of a melissima (tied/slurred note)."
549 'lyric-syllable-interface
550 "a single piece of lyrics"
554 ignore-length-mismatch
569 'multi-measure-rest-interface
570 "A rest that spans a whole number of measures. For typesetting the
571 numbers, fields from font-interface may be used.
573 padding is the space between number and rest. Measured in staffspace.
576 '( columns expand-limit minimum-width padding))
580 'paper-column-interface
583 '(column-space-strength before-musical-spacing-factor
584 stem-spacing-correction before-grace-spacing-factor when bounded-by-me
585 dir-list shortest-playing-duration shortest-starter-duration
586 contains-grace extra-space stretch-distance ))
592 "A porrectus ligature, joining two note heads into a single grob."
598 'spaceable-element-interface
599 "An grob (generally a Paper_column) that takes part in the
609 'rest-collision-interface
610 "Move around ordinary rests (not multi-measure-rests) to avoid
628 'script-column-interface
629 "An interface that sorts scripts according to their @code{script-priority}"
635 'spacing-spanner-interface
636 " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
637 The space taken by a note is determined by the formula
641 where TIME is the amount of time a note occupies. The value of C is
642 chosen such that the smallest space within a measure is
643 arithmetic_basicspace:
645 C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
647 The smallest space is the one following the shortest note in the
648 measure, or the space following a hypothetical 1/8 note. Typically
649 arithmetic_basicspace is set to a value so that the shortest note
650 takes about two noteheads of space (ie, is followed by a notehead of
654 2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
656 @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
657 @{ assuming: SHORTEST <= 1/8 @}
659 = arithmetic_multiplier *
660 ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
662 = arithmetic_multiplier * arithmetic_basicspace
664 @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
666 = quartwidth * arithmetic_basicspace
670 arithmetic_basicspace = 2/1 = 2
673 If you want to space your music wider, use something like:
675 arithmetic_basicspace = 4.;
679 maximum-duration-for-spacing
680 arithmetic-basicspace
681 arithmetic-multiplier
687 'staff-symbol-referencer-interface
689 "Object whose Y position is meaning with reference to a staff
690 symbol. Objects that have this interface should include
691 Staff_symbol_referencer::callback in their Y-offset-callback.
700 'staff-symbol-interface
701 "This spanner draws the lines of a staff. The middle line is
711 'stem-tremolo-interface
713 '( stem beam-width beam-thickness beam-space-function
718 'separation-item-interface
719 "Item that computes widths to generate spacing rods.
721 Calc dimensions for the Separating_group_spanner; this has to be
722 an item to get dependencies correct. It can't be an grob_group
723 since these usually are in a different X_group
731 'sustain-pedal-interface
737 'system-start-delimiter-interface
738 "#'style can be bar-line, bracket or brace"
739 '(bar-line-collapse-height brace-collapse-height bracket-collapse-height
740 thickness arch-height arch-angle arch-thick
741 arch-width bracket-thick glyph ))
745 'text-spanner-interface
746 "generic text spanner"
759 "A tie connecting two noteheads.
760 direction = Forced direction for all ties"
777 'tie-column-interface
778 "that sets tie directions in a tied chord"
783 'percent-repeat-interface
784 "Repeats that look like percent signs"
788 'volta-bracket-interface
789 "Volta bracket with number"
799 "A bar line that spans other barlines (typically used to get cross-staff barlines."
804 (primitive-eval (cons
806 (map (lambda (x) (list 'define (car x) (list 'quote (cdr x))))
810 (define (interface-names) (map (lambda (x) (symbol->string (car x))) all-interfaces))