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
80 outer-stem-length-limit
88 'staff-spacing-interface
94 'note-spacing-interface
111 'axis-group-interface
112 "a group of coupled grobs"
119 'note-column-interface
120 "Stem and noteheads combined"
134 beamed-minimum-lengths
166 extremity-offset-alist
176 'side-position-interface
177 "Position a victim object (this one) next to other objects (the support).
178 #'direction = where to put the victim object (left or right?)
181 side-support-elements
184 side-relative-direction
195 'accidentals-interface
207 'line-of-score-interface
208 "Super grob, parent of all:
210 The columns of a score that form one line. The toplevel grob. Any
211 grob has a Line_of_score as both X and Y reference point. The
212 Paper_score contains one grob of this type. Control enters the
213 Grob dependency calculation from this single Line_of_score
216 between-system-string
218 before-line-breaking-callback
219 after-line-breaking-callback
228 '( style stem-attachment-function ))
239 'rhythmic-head-interface
255 'tuplet-bracket-interface
256 "A bracket with a number in the middle, used for tuplets."
261 tuplet-bracket-visibility
262 tuplet-number-visibility
270 " Order grobs top to bottom/left to right/right to left etc."
284 "read by align-interface"
292 'break-aligned-interface
293 "Items that are aligned in prefatory matter"
303 'chord-name-interface
304 "generate a chord name"
305 '( pitches inversion bass))
309 'time-signature-interface
310 "A time signature, in different styles.
311 The following values for 'style are are recognized:
315 4/4 and 2/2 are typeset as C and struck C, respectively. All
316 other time signatures are written with two digits.
319 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
320 typeset with old-style mensuration marks. All other time
321 signatures are written with two digits.
324 All time signatures are typeset with a single
325 digit, e.g. 3/2 is written as 3. (Any symbol starting
326 with the digit @code{1} will do.)
328 @item @code{C}@var{M}@code{/}@var{N},
329 @code{old}@var{M}@code{/}@var{N} or
331 Tells LilyPond to use a specific symbol as time signature,
332 regardless of the actual time signature.
335 See also the test-file @file{input/test/time.ly}.
344 This is a request to print a special bar symbol. It replaces the
345 regular bar symbol with a special
346 symbol. The argument @var{bartype} is a string which specifies the
347 kind of bar to print. Options are @code{\":|\"}
348 @cindex \"|A@@@code{:|}
351 @cindex \"|B@@@code{|:}
353 @cindex \"|C@@@code{:|:}
356 @cindex \"|D@@@code{||}
358 @cindex \"|E@@@code{|.}
361 @cindex \"|F@@@code{.|}
363 @cindex \"|G@@@code{.|.}
366 These produce, respectively, a right repeat, a left repeat, a double
367 repeat, a double bar, a start bar, an end bar, and a thick double bar.
368 If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
369 but a line break is allowed at that spot.
372 '(bar-size-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function ))
379 padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
382 '( grow-direction thickness height padding
388 "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
389 '(stems arpeggio-direction))
394 'note-collision-interface
395 "An object that handles collisions between notes with different
396 stem directions and horizontal shifts. Most of the interesting
397 properties are to be set in @ref{note-column-interface}"
398 '(merge-differently-dotted note-width))
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]"
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))
435 "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
436 '(font-style font-series font-shape font-family font-name
437 font-design-size font-relative-size)
444 "A scheme markup text"
445 '(text align baseline-skip lookup raise kern magnify))
449 'dot-column-interface
450 "Interface that groups dots so they form a column"
457 "Any kind of loudness sign"
465 "A fingering instruction"
471 'separation-spanner-interface
472 "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
477 'text-script-interface
484 'grace-alignment-interface
485 "put grace notes in line"
493 'hara-kiri-group-interface
494 " As Vertical_group_spanner, but keep track of interesting items. If
495 we don't contain any interesting items after linebreaking, then
496 gracefully commit suicide. Objective: don't disgrace Lily by
497 typesetting empty lines in orchestral scores."
498 '( items-worth-living )
503 'line-spanner-interface
504 "Generic line drawn between two objects, eg. for use with glissandi.
505 gap is measured in staff-spaces. "
507 '(gap dash-period dash-length line-thickness type
512 'lyric-hyphen-interface
513 "A centred hyphen is a simple line between lyrics used to divide
514 syllables. The length of the hyphen line should stretch based on the
515 size of the gap between syllables."
517 '( thickness height minimum-length word-space
522 'key-signature-interface
523 "A group of accidentals."
532 'lyric-extender-interface
533 "The extender is a simple line at the baseline of the lyric
534 that helps show the length of a melissima (tied/slurred note)."
544 'lyric-syllable-interface
545 "a single piece of lyrics"
549 ignore-length-mismatch
564 'multi-measure-rest-interface
565 "A rest that spans a whole number of measures. For typesetting the
566 numbers, fields from font-interface may be used.
568 padding is the space between number and rest. Measured in staffspace.
571 '( columns expand-limit minimum-width padding))
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 'piano-pedal-interface
598 "A porrectus ligature, joining two note heads into a single grob."
604 'spaceable-element-interface
605 "An grob (generally a Paper_column) that takes part in the
615 'rest-collision-interface
616 "Move around ordinary rests (not multi-measure-rests) to avoid
634 'script-column-interface
635 "An interface that sorts scripts according to their @code{script-priority}"
641 'spacing-spanner-interface
642 " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
643 The space taken by a note is determined by the formula
647 where TIME is the amount of time a note occupies. The value of C is
648 chosen such that the smallest space within a measure is
649 arithmetic_basicspace:
651 C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
653 The smallest space is the one following the shortest note in the
654 measure, or the space following a hypothetical 1/8 note. Typically
655 arithmetic_basicspace is set to a value so that the shortest note
656 takes about two noteheads of space (ie, is followed by a notehead of
660 2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
662 @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
663 @{ assuming: SHORTEST <= 1/8 @}
665 = arithmetic_multiplier *
666 ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
668 = arithmetic_multiplier * arithmetic_basicspace
670 @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
672 = quartwidth * arithmetic_basicspace
676 arithmetic_basicspace = 2/1 = 2
679 If you want to space your music wider, use something like:
681 arithmetic_basicspace = 4.;
686 shortest-duration-space
692 'staff-symbol-referencer-interface
694 "Object whose Y position is meaning with reference to a staff
695 symbol. Objects that have this interface should include
696 Staff_symbol_referencer::callback in their Y-offset-callback.
705 'staff-symbol-interface
706 "This spanner draws the lines of a staff. The middle line is
716 'stem-tremolo-interface
718 '( stem beam-width beam-thickness
723 'separation-item-interface
724 "Item that computes widths to generate spacing rods.
726 Calc dimensions for the Separating_group_spanner; this has to be
727 an item to get dependencies correct. It can't be an grob_group
728 since these usually are in a different X_group
736 'system-start-delimiter-interface
737 "#'style can be bar-line, bracket or brace"
738 '(bar-line-collapse-height brace-collapse-height bracket-collapse-height
739 thickness arch-height arch-angle arch-thick
740 arch-width bracket-thick glyph ))
744 'text-spanner-interface
745 "generic text spanner"
760 "A tie connecting two noteheads.
761 direction = Forced direction for all ties"
778 'tie-column-interface
779 "that sets tie directions in a tied chord"
784 'percent-repeat-interface
785 "Repeats that look like percent signs"
789 'volta-bracket-interface
790 "Volta bracket with number"
800 "A bar line that spans other barlines (typically used to get cross-staff barlines."
805 (primitive-eval (cons
807 (map (lambda (x) (list 'define (car x) (list 'quote (cdr x))))
811 (define (interface-names) (map (lambda (x) (symbol->string (car x))) all-interfaces))