;;;;
;;;; source file of the GNU LilyPond music typesetter
;;;;
-;;;; (c) 1998--2001 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+;;;; (c) 1998--2003 Han-Wen Nienhuys <hanwen@cs.uu.nl>
;;;; Jan Nieuwenhuizen <janneke@gnu.org>
- ; should include default value?
+; should include default value?
-
-;;; FIXME: naming.
-;;; Score elements are called `objects' now and then, which gets
-;;; rather confusing, we now have `elements', `items', `spanners'
-;;; and `objects'.
-
-
-(define all-interfaces '())
-
-(define (lily-interface symbol description props)
- (set! all-interfaces (acons symbol (list symbol
- description
- props) all-interfaces)
- )
- )
-
-(define (grob-description . interfaces)
- (let* ((ifs (cons grob-interface interfaces))
- (props (map caddr ifs))
- ; (prop-typep-pairs (map (lambda (x) (cons (car x) (cadr x)))
- ; (apply append props)))
- (syms (map car ifs))
- )
- (list (cons 'separator "\n\n\n") ;easy printing.
- (cons 'interfaces syms)
- (cons 'interface-descriptions ifs)
- ; (cons 'interface-descriptions (cadr merged))
- ;; description of the grob itself?
- ; (cons 'properties prop-typep-pairs)
- )))
-
-
-(lily-interface
- 'grob-interface
- "All grobs support this"
- '(
- X-offset-callbacks
- Y-offset-callbacks
- X-extent-callback
- Y-extent-callback
- molecule-callback
- font-relative-size
- extra-offset
- interfaces
- dependencies
- no-spacing-rods
- extra-extent-X
- extra-extent-Y
- minimum-extent-X
- minimum-extent-Y
- origin
- transparent
- ))
-
-
-(lily-interface
- 'beam-interface
- "A beam.
-
-#'thickness= weight of beams, in staffspace
- "
- '(auto-knee-gap
- staff-position
- height
- flag-width-function
- damping
- neutral-direction
- thickness
- space-function
- beamed-stem-shorten
- height-quants
- vertical-position-quant-function
- damping
- outer-stem-length-limit
- slope-limit
- auto-knee-gap
- )
- )
-
-
-(lily-interface
- 'clef-interface
- "A clef sign"
- '(
- non-default
- full-size-change
- glyph
- ))
-
-
-
-(lily-interface
- 'axis-group-interface
- "a group of coupled grobs"
- '(
- axes
- ))
-
-
-(lily-interface
- 'note-column-interface
- "Stem and noteheads combined"
- '(
- horizontal-shift
- force-hshift
- ))
-
-
-(lily-interface
- 'stem-interface
- "A stem"
- '(
- thickness
- beamed-lengths
- beamed-minimum-lengths
- lengths
- beam
- stem-shorten
- duration-log
- beaming
- neutral-direction
- stem-end-position
- support-head
- heads
- direction
- length
- style
- flag-style
- dir-forced
- ))
-
-
-
-(lily-interface
- 'slur-interface
- "A slur"
- '(
- de-uglify-parameters
- details
- attachment
- direction
- attachment-offset
- beautiful
- y-free
- control-points
- extremity-rules
- extremity-offset-alist
- thickness
- dashed
-
- )
- )
-
-
-
-(lily-interface
- 'side-position-interface
- "Position a victim object (this one) next to other objects (the support).
-#'direction = where to put the victim object (left or right?)
-"
- '(
- side-support
- direction-source
- direction
- side-relative-direction
- minimum-space
- padding
- self-alignment-X
- self-alignment-Y
-
- )
- )
-
-
-(lily-interface
- 'accidentals-interface
- "Accidentals"
- '(
- left-padding
- right-padding
- ))
-
-
-
-(lily-interface
- 'line-of-score-interface
- "Super grob, parent of all:
-
-The columns of a score that form one line. The toplevel grob. Any
-grob has a Line_of_score as both X and Y reference point. The
-Paper_score contains one grob of this type. Control enters the
-Grob dependency calculation from this single Line_of_score
-object."
- '(
- between-system-string
- spacing-procedure
- before-line-breaking-callback
- after-line-breaking-callback
- all-elements
- columns
- ))
-
-
-(lily-interface
- 'note-head-interface
- "Note head"
- '( style stem-attachment-function note-character ))
-
-
-(lily-interface
- 'note-name-interface
+(ly:add-interface
+'note-name-interface
"Note name"
- '( style ))
-
-
-
-(lily-interface
- 'rhythmic-head-interface
- "Note head or rest"
- '(
- dot
- stem
- duration-log
- ))
-
-
-(lily-interface
- 'rest-interface
- "a rest"
- '(style ))
-
-
-(lily-interface
- 'tuplet-bracket-interface
- "A bracket with a number in the middle, used for tuplets."
- '(
- columns
- number-gap
- delta-y
- tuplet-bracket-visibility
- tuplet-number-visibility
- thick
- direction
- ))
-
-
-(lily-interface
- 'align-interface
- " Order grobs top to bottom/left to right/right to left etc."
- '(
- stacking-dir
- align-dir
- threshold
- alignment-done
- center-element
- elements
- axes
- ))
-
-
-(lily-interface
- 'aligned-interface
- "read by align-interface"
- '(
- minimum-space
- extra-space
- ))
-
-
-(lily-interface
- 'break-aligned-interface
- "Items that are aligned in prefatory matter"
- '(
- break-align-symbol
- visibility-lambda
- breakable
- ))
-
-
-(lily-interface
- 'chord-name-interface
- "generate a chord name"
- '( pitches inversion bass))
-
-
-(lily-interface
- 'time-signature-interface
- "A time signature, in different styles.
- The following values for 'style are are recognized:
-
- @table @samp
- @item @code{C}
- 4/4 and 2/2 are typeset as C and struck C, respectively. All
- other time signatures are written with two digits.
-
- @item @code{old}
- 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
- typeset with old-style mensuration marks. All other time
- signatures are written with two digits.
-
- @item @code{1xxx}
- All time signatures are typeset with a single
- digit, e.g. 3/2 is written as 3. (Any symbol starting
- with the digit @code{1} will do.)
-
- @item @code{C}@var{M}@code{/}@var{N},
-@code{old}@var{M}@code{/}@var{N} or
- @code{old6/8alt}
- Tells LilyPond to use a specific symbol as time signature,
- regardless of the actual time signature.
- @end table
-
-See also the test-file @file{input/test/time.ly}.
-"
- '(fraction style ))
-
-
-(lily-interface
- 'bar-line-interface
- "Bar line.
-
-This is a request to print a special bar symbol. It replaces the
-regular bar symbol with a special
-symbol. The argument @var{bartype} is a string which specifies the
-kind of bar to print. Options are @code{\":|\"}
-@cindex \"|A@@@code{:|}
-,
-@code{\"|:\"}
-@cindex \"|B@@@code{|:}
-, @code{\":|:\"}
-@cindex \"|C@@@code{:|:}
-,
-@code{\"||\"}
-@cindex \"|D@@@code{||}
-, @code{\"|.\"}
-@cindex \"|E@@@code{|.}
-,
-@code{\".|\"}
-@cindex \"|F@@@code{.|}
-, and @code{\".|.\"}
-@cindex \"|G@@@code{.|.}
-.
-
-These produce, respectively, a right repeat, a left repeat, a double
-repeat, a double bar, a start bar, an end bar, and a thick double bar.
-If @var{bartype} is set to @code{\"empty\"} then nothing is printed,
-but a line break is allowed at that spot.
-
-"
- '(bar-size-procedure kern thin-kern hair-thickness thick-thickness glyph bar-size break-glyph-function ))
-
-
-(lily-interface
- 'hairpin-interface
- "hairpin crescendo.
-
-padding -- horizontal padding. This is useful if a crescendo is set next to a text like `mf'
-
-"
- '( grow-direction thickness height padding
- ))
-
-
-(lily-interface
- 'arpeggio-interface
- "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
- '(stems))
-
-
-
-(lily-interface
- 'note-collision-interface
- "An object that handles collisions between notes with different
-stem directions and horizontal shifts. Most of the interesting
-properties are to be set in @ref{note-column-interface}"
- '(merge-differently-dotted note-width))
-
-
-
-(lily-interface
- 'custos-interface
- "A custos is a staff context symbol that appears at the end of a
- staff line with monophonic musical contents (i.e. with a single
- voice). It anticipates the pitch of the first note of the following
- line and thus helps the player or singer to manage line breaks
- during performance, thus enhancing readability of a score.
-
- Custodes were frequently used in music notation until the 16th
- century. There were different appearences for different notation
- styles. Nowadays, they have survived only in special forms of
- musical notation such as via the editio vaticana dating back to the
- beginning of the 20th century.
-
-[TODO: add to glossary]"
-
- '(style))
-
-
+ '(style))
-
-
-
- (lily-interface
- 'dots-interface
- "The dots to go with a notehead/rest. A separate interface, since they
-are a party in collision resolution.
-#'direction is the Direction to handle staff-line collisions in."
- '(direction dot-count))
-
-
- (lily-interface
- 'font-interface
- "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
- '(font-style font-series font-shape font-family font-name
-font-design-size font-relative-size)
- )
-
-
-
- (lily-interface
- 'text-interface
- "A scheme markup text"
- '(text align baseline-skip lookup raise kern magnify))
-
-
- (lily-interface
- 'dot-column-interface
- "Interface that groups dots so they form a column"
- '( )
- )
-
-
- (lily-interface
- 'dynamic-interface
+(ly:add-interface
+ 'dynamic-interface
"Any kind of loudness sign"
'()
)
+(ly:add-interface
+ 'finger-interface
+ "A fingering instruction"
+ '()
+ )
+(ly:add-interface
+ 'rhythmic-grob-interface
+ "Any object with a rhythmic basis. Used to determine which grobs
+are interesting enough to maintain a hara-kiri staff."
+ '()
+ )
- (lily-interface
- 'finger-interface
- "A fingering instruction"
- '()
- )
-
-
- (lily-interface
- 'separation-spanner-interface
- "Spanner that containing @code{separation-item-interface} grobs to calculate rods"
- '()
- )
-
- (lily-interface
- 'text-script-interface
- "Any text script"
- '()
- )
-
-
- (lily-interface
- 'grace-alignment-interface
- "put grace notes in line"
- '(
- horizontal-space
- )
- )
-
-
- (lily-interface
- 'hara-kiri-group-interface
- " As Vertical_group_spanner, but keep track of interesting items. If
-we don't contain any interesting items after linebreaking, then
-gracefully commit suicide. Objective: don't disgrace Lily by
-typesetting empty lines in orchestral scores."
- '( items-worth-living )
-)
-
-
- (lily-interface
- 'line-spanner-interface
- "Generic line drawn between two objects, eg. for use with glissandi.
-gap is measured in staff-spaces. "
-
- '(gap dash-period dash-length line-thickness type
- ))
-
+(ly:add-interface
+ 'ligature-interface
+ "A ligature"
+ '()
+ )
- (lily-interface
- 'lyric-hyphen-interface
- "A centred hyphen is a simple line between lyrics used to divide
-syllables. The length of the hyphen line should stretch based on the
-size of the gap between syllables."
+(ly:add-interface
+ 'ligature-bracket-interface
+ "A bracket indicating a ligature in the original edition"
+ '(width thickness height ligature-primitive-callback))
- '( thickness height minimum-length word-space
+(ly:add-interface
+ 'mark-interface
+ "a rehearsal mark"
+ '(
))
-
- (lily-interface
- 'key-signature-interface
- "A group of accidentals."
- '(
- c0-position
- old-accidentals
- new-accidentals
- ))
-
-
- (lily-interface
- 'lyric-extender-interface
- "The extender is a simple line at the baseline of the lyric
-that helps show the length of a melissima (tied/slurred note)."
- '(
- word-space
- height
- right-trim-amount
- ))
-
-
-
- (lily-interface
- 'lyric-syllable-interface
- "a single piece of lyrics"
- '(
- word-space
- ))
-
-
-
- (lily-interface
- 'mark-interface
- "a rehearsal mark"
- '(
- ))
+;;; todo: this is not typesetting info. Move to interpretation.
+(ly:add-interface
+ 'tablature-interface
+ "tablature notes"
+ '())
- (lily-interface
- 'multi-measure-rest-interface
- "A rest that spans a whole number of measures. For typesetting the
-numbers, fields from font-interface may be used.
-padding is the space between number and rest. Measured in staffspace.
+;; todo: figure out where to put this doco:
"
- '( columns expand-limit minimum-width padding))
-
-
- (lily-interface
- 'paper-column-interface
- ""
-
- '(column-space-strength before-musical-spacing-factor
-stem-spacing-correction before-grace-spacing-factor when bounded-by-me
-dir-list shortest-playing-duration shortest-starter-duration
-contains-grace extra-space stretch-distance ))
-
-
-
- (lily-interface
- 'porrectus-interface
- "A porrectus ligature, joining two note heads into a single grob."
- '(
- ))
-
-
- (lily-interface
- 'spaceable-element-interface
- "An grob (generally a Paper_column) that takes part in the
-spacing problem. "
- '(
- minimum-distances
- ideal-distances
- dir-list
- ))
-
-
- (lily-interface
- 'rest-collision-interface
- "Move around ordinary rests (not multi-measure-rests) to avoid
-conflicts."
- '(
- maximum-rest-count
- minimum-distance
- elements
- ))
-
-
- (lily-interface
- 'script-interface
- ""
- '(
- script-priority
- ))
-
-
- (lily-interface
- 'script-column-interface
- "An interface that sorts scripts according to their @code{script-priority}"
- '( ))
-
-
-
- (lily-interface
- 'spacing-spanner-interface
- " SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
-The space taken by a note is determined by the formula
-
-
-
-where TIME is the amount of time a note occupies. The value of C is
-chosen such that the smallest space within a measure is
-arithmetic_basicspace:
-
-C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
-
-The smallest space is the one following the shortest note in the
-measure, or the space following a hypothetical 1/8 note. Typically
-arithmetic_basicspace is set to a value so that the shortest note
-takes about two noteheads of space (ie, is followed by a notehead of
-space):
-
-@example
-2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
-
-@{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
-@{ assuming: SHORTEST <= 1/8 @}
-
-= arithmetic_multiplier *
-( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
-
-= arithmetic_multiplier * arithmetic_basicspace
-
-@{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
-
-= quartwidth * arithmetic_basicspace
-
-=>
-
-arithmetic_basicspace = 2/1 = 2
-
-
-If you want to space your music wider, use something like:
-
-arithmetic_basicspace = 4.;
-
-@end example"
- '(
- maximum-duration-for-spacing
- arithmetic-basicspace
- arithmetic-multiplier
-
- ))
-
-
- (lily-interface
- 'staff-symbol-referencer-interface
-
- "Object whose Y position is meaning with reference to a staff
-symbol. Objects that have this interface should include
-Staff_symbol_referencer::callback in their Y-offset-callback.
+Grob properties form a name space where you can set variables per
+object. Each object however, may have multiple functions. For
+example, consider a dynamic symbol, such @code{\ff} (fortissimo). It
+is printed above or below the staff, it is a dynamic sign, and it is a
+kind of text.
+
+To reflect this different functions of a grob, procedures and variables
+are grouped into so-called interfaces. The dynamic text for example
+supports the following interfaces:
+@table @code
+@item font-interface
+ The glyph is built from characters from a font, hence the
+@code{font-interface}. For objects supporting @code{font-interface}, you
+can select alternate fonts by setting @code{font-style},
+@code{font-point-size}, etc.
+
+@item dynamic-interface
+ Dynamic interface is not associated with any variable or function in
+particular, but this makes it possible to distinguish this grob from
+other similar grobs (like @code{TextScript}), that have no meaning of
+dynamics.
+
+@item text-interface
+ This interface is for texts that are to be set using special routines
+to stack text into lines, using kerning, etc.
+
+@item general-grob-interface
+ This interface is supported by all grob types.
+@end table
"
- '(
- staff-symbol
- staff-position
- ))
-
-
- (lily-interface
- 'staff-symbol-interface
- "This spanner draws the lines of a staff. The middle line is
-position 0."
- '(
- staff-space
- line-count
- invisible-staff
- ))
-
-
- (lily-interface
- 'stem-tremolo-interface
- ""
- '( stem beam-width beam-thickness beam-space-function
- ))
-
-
- (lily-interface
- 'separation-item-interface
- "Item that computes widths to generate spacing rods.
-
-Calc dimensions for the Separating_group_spanner; this has to be
-an item to get dependencies correct. It can't be an grob_group
-since these usually are in a different X_group
-"
- '(
- elements
- ))
-
-
- (lily-interface
- 'sustain-pedal-interface
- ""
- '(
- ))
-
- (lily-interface
- 'system-start-delimiter-interface
- "#'style can be bar-line, bracket or brace"
- '(bar-line-collapse-height brace-collapse-height bracket-collapse-height
- thickness arch-height arch-angle arch-thick
- arch-width bracket-thick glyph ))
-
-
- (lily-interface
- 'text-spanner-interface
- "generic text spanner"
- '(
- dash-period
- dash-length
- line-thickness
- edge-height
- edge-text
- type
-))
-
-
- (lily-interface
- 'tie-interface
- "A tie connecting two noteheads.
-direction = Forced direction for all ties"
-
- '(
- staffline-clearance
- control-points
- heads
- details
- thickness
- x-gap
- direction
- minimum-length
- ))
-
-
-
-
- (lily-interface
- 'tie-column-interface
- "that sets tie directions in a tied chord"
- '(direction
- ))
-
-(lily-interface
- 'percent-repeat-interface
- "Repeats that look like percent signs"
- '(slope thickness))
-
-(lily-interface
- 'volta-bracket-interface
- "Volta bracket with number"
- '(
- bars
- thickness
- height
- ))
-
-
-(lily-interface
- 'span-bar-interface
- "A bar line that spans other barlines (typically used to get cross-staff barlines."
- '(
- ))
-
-
-(primitive-eval (cons
- 'begin
- (map (lambda (x) (list 'define (car x) (list 'quote (cdr x))))
- all-interfaces)))
-
-
-(define (interface-names) (map (lambda (x) (symbol->string (car x))) all-interfaces))
-
-