scm/interface.scm

   1
   2 ; should include default value?
   3
   4
   5 ;;; FIXME: naming.
   6 ;;; Score elements are called `objects' now and then, which gets
   7 ;;; rather confusing, we now have `elements', `items', `spanners'
   8 ;;; and `objects'.
   9
  10
  11 (define (elt-property-description symbol type? description)
  12   (list symbol type? description))
  13
  14 (define (lily-interface symbol description props)
  15   (list symbol
  16         description
  17         props
  18         )
  19   )
  20
  21 (define (boolean-or-symbol? x) (or boolean? x) (or symbol? x))
  22
  23 (define (uniqued-alist  alist acc)
  24   (if (null? alist) acc
  25       (if (assoc (caar alist) acc)
  26           (uniqued-alist (cdr alist) acc)
  27           (uniqued-alist (cdr alist) (cons (car alist) acc)
  28   ))))
  29
  30 (define (element-description name . interfaces)
  31   (let* ((ifs (cons general-element-interface interfaces))
  32          (props (map caddr ifs))
  33          (prop-typep-pairs (map (lambda (x) (cons (car x) (cadr x)))
  34                                         (apply append props)))
  35          (syms (map car ifs))
  36         )
  37     (list (cons 'separator "\n\n\n")    ;easy printing.
  38           (cons 'name name)
  39           (cons 'interfaces syms)
  40           (cons 'interface-descriptions ifs)
  41           ; (cons 'interface-descriptions (cadr merged))
  42           ;; description of the element itself?
  43           (cons 'properties prop-typep-pairs)
  44   )))
  45
  46
  47 (define general-element-interface
  48   (lily-interface
  49    'general-element-interface
  50    "All elements support this"
  51    (list
  52     (elt-property-description 'X-offset-callbacks list? "list of functions, each taking an element and axis argument. The function determine the position relative to this element's parent. The last one in the list is called first")
  53     (elt-property-description 'Y-offset-callbacks list? "see @code{X-offset-callbacks}")
  54     (elt-property-description 'X-extent-callback procedure? "procedure taking an element and axis argument, returning a number-pair. The return value is the extent of the element.")
  55     (elt-property-description 'Y-extent-callback procedure? "see @code{X-extent-callback}")
  56     (elt-property-description 'font-relative-size integer? "")
  57     (elt-property-description 'extra-offset number-pair? "pair of reals (a cons) forcing an extra offset   before outputting")
  58     (elt-property-description 'interfaces  list? "list of symbols indicating the interfaces supported by this object. Is initialized from the @code{meta} field.")
  59     (elt-property-description 'dependencies list? "list of score-element pointers that indicate who to compute first for certain global passes")
  60     (elt-property-description 'no-spacing-rods boolean? "read from elements: boolean that makes Separation_item ignore this item (MOVE ME TO ITEM)")
  61     (elt-property-description 'extra-extent-X number-pair? "enlarge in X dimension by this much, measured in staff space")
  62     (elt-property-description 'extra-extent-Y number-pair? "see @code{extra-extent-Y}")
  63     (elt-property-description 'minimum-extent-X number-pair? "minimum size in X dimension, measured in staff space")
  64     (elt-property-description 'minimum-extent-Y number-pair? "see @code{minimum-extent-Y}")
  65     (elt-property-description 'origin ly-input-location? "location in input file of the definition")
  66     (elt-property-description 'transparent boolean? "This is almost the
  67 same as setting molecule-callback to #f, but this retains the
  68 dimensions of this element, which means that you can erase elements
  69 individually. ")
  70     (elt-property-description 'molecule-callback procedure? "Function taking graphical element as argument, returning a Scheme encoded Molecule
  71
  72 This function can be called more than once (for instance once for
  73 computing dimensions, and once for computing the output).  Therefore,
  74 this function should have no side-effects on its argument.
  75 Caching of computed values is permissible, and generally useful, though.
  76
  77 ")
  78     ))
  79   )
  80
  81 (define beam-interface
  82   (lily-interface
  83    'beam-interface
  84    "A beam. "
  85    (list
  86     (elt-property-description 'y-position number? "position of left edge")
  87     (elt-property-description 'height number? "dy")
  88     (elt-property-description 'flag-width-function procedure? "")
  89     (elt-property-description 'damping integer? "amount of beam slope damping should beam slope be damped? 0: no, 1: yes, 100000: horizontal beams ")
  90     (elt-property-description 'default-neutral-direction dir? "which
  91 direction to choose if we're in the middle of the staff ")
  92     (elt-property-description 'thickness number? "weight of beams, in staffspace")
  93     (elt-property-description 'space-function procedure? "function of type multiplicity -> real (in staffspace)")
  94     (elt-property-description 'beamed-stem-shorten number? "shorten beamed stems in forced direction")
  95     (elt-property-description 'height-quants procedure? "function of type (beam staff-line-thickness) -> list of quants.  Default value: default-beam-dy-quants.
  96 ")
  97     (elt-property-description 'vertical-position-quant-function procedure? "
  98 function of type (beam multiplicity dy staff-line-thickness) -> real.  Default value: default-beam-y-quants, also available: beam-traditional-y-quants.
  99 ")
 100     (elt-property-description 'dir-function procedure? "function of type (count total)->direction.  Default value: beam-dir-majority, also available: beam-dir-mean, beam-dir-median.")
 101     (elt-property-description 'damping number? "damping factor.")
 102     (elt-property-description 'outer-stem-length-limit number? "catch
 103 suspect beam slopes, set slope to zero if outer stem is lengthened
 104 more than this (in staffspace)")
 105     (elt-property-description 'slope-limit number? "set slope to zero if slope is running away steeper than this.")
 106     )
 107    ))
 108
 109
 110 (define clef-interface
 111   (lily-interface
 112    'clef-interface
 113    "A clef sign"
 114    (list
 115     (elt-property-description 'non-default boolean? "not set because of existence of a bar?")
 116     (elt-property-description 'full-size-change boolean? "if set, don't make a change clef smaller.")
 117     (elt-property-description 'glyph string? "a string determining what glyph is typeset")
 118     ))
 119   )
 120
 121 (define axis-group-interface
 122   (lily-interface
 123    'axis-group-interface
 124    "a group of coupled elements"
 125    (list
 126     (elt-property-description 'axes list? "list of axis (number) in which this group works")
 127    )))
 128
 129 (define note-column-interface
 130   (lily-interface
 131    'note-column-interface
 132    "Stem and noteheads combined"
 133    (list
 134     (elt-property-description 'horizontal-shift integer? "integer that identifies ranking of note-column for horizontal shifting. This is used by @ref{note-collision-interface}")
 135     (elt-property-description 'force-hshift number? "amount of collision_note_width that overides automatic collision settings. This is used by @ref{note-collision-interface}")
 136     ))
 137   )
 138
 139 (define stem-interface
 140   (lily-interface
 141    'stem-interface
 142    "A stem"
 143    (list
 144     (elt-property-description 'thickness number? "thickness, measured in stafflinethickness")
 145     (elt-property-description 'beamed-lengths list? "list of stem lengths given beam multiplicity ")
 146     (elt-property-description 'beamed-minimum-lengths list? "list of minimum stem lengths given beam multiplicity")
 147     (elt-property-description 'stem-centered boolean? "Center stems on note heads. Useful for mensural notation")
 148     (elt-property-description 'lengths list? "Stem length given multiplicity of flag")
 149     (elt-property-description 'beam ly-element? "pointer to the beam, if applicable")
 150     (elt-property-description 'stem-shorten list? "shorten stems in forced directions given flag multiplicity")
 151     (elt-property-description 'duration-log integer? "log of the duration, ie. 0=whole note, 1 = half note, etc.")
 152     (elt-property-description 'beaming number-pair? "number of beams extending to left and right")
 153     (elt-property-description 'default-neutral-direction dir? "Where to go if we're in the middle of the staff")
 154     (elt-property-description 'stem-end-position number? "Where does the stem end (the end is opposite to the support-head")
 155     (elt-property-description 'support-head ly-element? "the note head at
 156 one end of the stem")
 157     (elt-property-description 'heads list? "list of note heads")
 158     (elt-property-description 'direction dir? "up or down")
 159     (elt-property-description 'stem-length number? "length of stem")
 160     (elt-property-description 'style string? "") ; symbol!?
 161     (elt-property-description 'flag-style string? "") ; symbol!?
 162     (elt-property-description 'dir-forced boolean? "set if direction has been forced; read by Beam.")
 163     )))
 164
 165
 166 (define slur-interface
 167   (lily-interface
 168    'slur-interface
 169    "A slur"
 170    (list
 171     (elt-property-description 'de-uglify-parameters list? "list of 3 real constants. They define the valid areas for the middle control points. Used in de_uglyfy. They are a bit empirical.")
 172     (elt-property-description 'details list? "alist containing contaning a few magic constants.")
 173     (elt-property-description 'attachment pair? "cons of symbols, '(LEFT-TYPE . RIGHT-TYPE), where both types may be alongside-stem, stem, head or loose-end")
 174     (elt-property-description 'direction dir? "up or down?")
 175    (elt-property-description 'attachment-offset pair? "cons of offsets, '(LEFT-offset . RIGHT-offset).  This offset is added to the attachments to prevent ugly slurs.")
 176      (elt-property-description 'beautiful number? "number that dictates when a slur should be de-uglyfied.  It correlates with the enclosed area between noteheads and slurs.  A value of 0.1 yields only undisturbed slurs, a value of 5 will tolerate quite high blown slurs.")
 177      (elt-property-description 'y-free number? "minimal vertical gap between slur and noteheads or stems")
 178      (elt-property-description 'control-points list? "[internal] control points of bezier curve")
 179      (elt-property-description 'extremity-rules  list? "an alist (procedure slur dir) -> attachment to determine the attachment (see above).  If procedure returns #t, attachment is used.  Otherwise, the next procedure is tried.")
 180      (elt-property-description 'extremity-offset-alist list? "an alist (attachment stem-dir*dir slur-dir*dir) -> offset.  The offset adds to the centre of the notehead, or stem.")
 181      (elt-property-description 'thickness list? "The thickness[stafflinethickness] of slur in the centre.")
 182      (elt-property-description 'dashed number? "[FIXME: use dash-period/dash length; see text-spanner] number representing the length of the dashes.")
 183
 184     )
 185    )
 186   )
 187
 188 (define side-position-interface
 189   (lily-interface
 190    'side-position-interface
 191    "Position a victim object (this one) next to other objects (the support)."
 192    (list
 193    (elt-property-description 'side-support list? "the support, a list of score elements")
 194    (elt-property-description 'direction-source ly-element? "in case side-relative-direction is set, which element  to get the direction from ")
 195     (elt-property-description 'direction dir? "where to put the victim object (left or right?)")
 196     (elt-property-description 'side-relative-direction dir? "if set: get the direction from a different object, and multiply by this.")
 197     (elt-property-description 'minimum-space number? "minimum distance that the victim should move (after padding)")
 198     (elt-property-description 'padding number? "add this much extra space between victim and support")
 199     (elt-property-description 'self-alignment-X number? "real number: -1 =
 200 left aligned, 0 = center, 1 right-aligned in X direction.
 201
 202  Set to an element pointer, if you want that element to be the center.
 203 In this case, the center element should have this object as a
 204 reference point.
 205 ")
 206     (elt-property-description 'self-alignment-Y number? "like self-alignment-X but for Y axis")
 207
 208     )
 209   ))
 210
 211 (define accidentals-interface
 212   (lily-interface
 213    'accidentals-interface
 214    "Accidentals"
 215    (list
 216     (elt-property-description 'left-padding number? "space left of accs")
 217     (elt-property-description 'right-padding number? "space right of accs")
 218     )
 219    ))
 220
 221 (define line-of-score-interface
 222   (lily-interface
 223    'line-of-score-interface
 224    "Super element, parent of all:
 225
 226 The columns of a score that form one line.  The toplevel element.  Any
 227 element has a Line_of_score as both X and Y reference point. The
 228 Paper_score contains one element of this type. Control enters the
 229 Score_element dependency calculation from this single Line_of_score
 230 object."
 231    (list
 232     (elt-property-description 'between-system-string string? "string
 233  to dump between two systems. Useful for forcing pagebreaks")
 234     (elt-property-description 'spacing-procedure procedure? "procedure taking
 235 graphical element as argument. This is called after before-line-breaking-callback, but before the actual line breaking itself.  Return value is ignored")
 236     (elt-property-description 'before-line-breaking-callback procedure?
 237                           "Procedure taking graphical element as argument.
 238 This procedure is called (using dependency resolution) before line breaking, but after generating discretionary items. Return value is ignored")
 239     (elt-property-description 'after-line-breaking-callback procedure?
 240                           "Procedure taking graphical element as argument.
 241 This procedure is called (using dependency resolution) after line breaking. Return value is ignored")
 242     (elt-property-description 'all-elements list? "list of all score elements in this line. Needed for protecting elements from GC.")
 243     (elt-property-description 'columns list? "list of all paper columns")
 244     )))
 245
 246 (define note-head-interface
 247   (lily-interface
 248    'note-head-interface
 249    "Note head"
 250    (list
 251     (elt-property-description 'style symbol? "symbol that sets note head style")
 252     )
 253    ))
 254
 255 (define note-name-interface
 256   (lily-interface
 257    'note-name-interface
 258    "Note name"
 259    (list
 260     (elt-property-description 'style symbol? "symbol that sets note name style")
 261     )
 262    ))
 263
 264
 265 (define rhythmic-head-interface
 266   (lily-interface
 267    'rhythmic-head-interface
 268    "Note head or rest"
 269    (list
 270     (elt-property-description 'dot ly-element? "reference to Dots object.")
 271     (elt-property-description 'stem ly-element? "pointer to Stem object")
 272     (elt-property-description 'duration-log integer? "2-log of the notehead duration")
 273     )))
 274
 275 (define rest-interface
 276   (lily-interface
 277    'rest-interface
 278    "a rest"
 279    (list
 280     (elt-property-description 'style string? "string specifying glyph style"))))
 281
 282 (define tuplet-bracket-interface
 283   (lily-interface
 284    'tuplet-bracket-interface
 285    "A bracket with a number in the middle, used for tuplets."
 286    (list
 287     (elt-property-description 'beams list? "list of beam ptrs.")
 288     (elt-property-description 'columns list? " list of note-columns.")
 289     (elt-property-description 'number-gap number? "")
 290     (elt-property-description 'delta-y number? "amount of ascension")
 291     (elt-property-description 'tuplet-bracket-visibility boolean-or-symbol? "
 292 This controls the visibility of the tuplet bracket.
 293 Setting it to false will prevent printing of the
 294 bracket. Setting the property to #'if-no-beam will make it
 295 print only if there is no beam associated with this tuplet bracket.")
 296     (elt-property-description 'tuplet-number-visibility boolean-or-symbol? "
 297 Like @code{tuplet-bracket-visibility}, but for the number.")
 298     (elt-property-description 'parallel-beam boolean? "internal: true if there is a beam just as wide as the bracket ")
 299     (elt-property-description 'thick number? "thickness, in stafflinethickness")
 300     )
 301 ))
 302
 303
 304 (define align-interface
 305   (lily-interface
 306    'align-interface
 307    " Order elements top to bottom/left to right/right to left etc."
 308    (list
 309     (elt-property-description 'stacking-dir  dir? "stack contents of elements in which direction ?")
 310     (elt-property-description 'align-dir  dir? "Which side to align? -1: left side, 0: around center of width, 1: right side")
 311     (elt-property-description 'threshold  number-pair? "(cons MIN MAX), where MIN and MAX are dimensions in staffspace")
 312     (elt-property-description 'alignment-done  boolean? "boolean to administrate whether we've done the alignment already (to ensure that the process is done only once)")
 313     (elt-property-description 'center-element ly-element? "element which will be at the
 314 center of the group after aligning (when using
 315 Align_interface::center_on_element). ")
 316     (elt-property-description 'elements  list? "to be aligned elements ")
 317     (elt-property-description 'axes  list? "list of axis numbers. Should contain only one number.")
 318     )))
 319
 320 (define aligned-interface
 321   (lily-interface
 322    'aligned-interface
 323    "read by align-interface"
 324    (list
 325     (elt-property-description 'minimum-space number-pair? "(cons LEFT RIGHT)")
 326     (elt-property-description 'extra-space number-pair? "(cons LEFT RIGHT)")
 327     )))
 328
 329 (define break-aligned-interface
 330   (lily-interface
 331    'break-aligned-interface
 332    "Items that are aligned in prefatory matter"
 333    (list
 334     (elt-property-description 'break-align-symbol symbol? "the index in the spacing table (symbol) of the to be aligned item.")
 335     (elt-property-description 'visibility-lambda procedure? "a function that takes the break direction and returns a  cons of booleans containing (TRANSPARENT . EMPTY)")
 336     (elt-property-description 'breakable boolean? "boolean indicating if this is a breakable item (clef, barline, key sig, etc.)")
 337     )))
 338
 339 (define chord-name-interface
 340   (lily-interface
 341    'chord-name-interface
 342    "generate a chord name"
 343    (list
 344     (elt-property-description 'pitches list? "list of musical-pitch")
 345     (elt-property-description 'inversion list? " musical-pitch, optional")
 346     (elt-property-description 'bass list? " musical-pitch, optional")
 347    )))
 348
 349 (define time-signature-interface
 350   (lily-interface
 351    'time-signature-interface
 352    "A time signature, in different styles"
 353    (list
 354     (elt-property-description 'fraction number-pair? "")
 355     (elt-property-description 'style string? "")
 356     )))
 357
 358 (define bar-line-interface
 359   (lily-interface
 360    'bar-line-interface
 361    "Bar line"
 362    (list
 363     (elt-property-description 'barsize-procedure procedure? "how to compute the size of a bar line")
 364     (elt-property-description 'kern number? "space after a thick line")
 365     (elt-property-description 'thin-kern number? "space after a hair-line")
 366     (elt-property-description 'hair-thickness number? "thickness, measured in stafflinethickness")
 367     (elt-property-description 'thick-thickness number? "thickness, measured in stafflinethickness")
 368     (elt-property-description 'glyph string? "what kind barline? A concatenation of |, : and .")
 369     (elt-property-description 'bar-size number? "")
 370     (elt-property-description 'break-glyph-function procedure? "function taking glyph and break-direction, returning the glyph at a line break")
 371    )))
 372
 373
 374
 375
 376 (define hairpin-interface
 377   (lily-interface
 378    'hairpin-interface
 379    "hairpin crescendo"
 380    (list
 381     (elt-property-description 'grow-direction dir? "crescendo or decrescendo?")
 382     (elt-property-description 'thickness number? "thickness, measured in stafflinethickness")
 383     (elt-property-description 'height number? "height, measured in staffspace.")
 384     (elt-property-description 'padding number? "horizontal padding. This is useful if a crescendo is set next to a text like `mf'")
 385     )))
 386
 387 (define arpeggio-interface
 388   (lily-interface
 389    'arpeggio-interface
 390    "Functions and settings for drawing an arpeggio symbol (a wavy line left to noteheads."
 391    (list
 392     (elt-property-description 'stems list? "list of stem objects, corresponding to the notes that the arpeggio has to be before.")
 393     )
 394    )
 395   )
 396
 397 (define note-collision-interface
 398   (lily-interface
 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    (list
 404     (elt-property-description 'merge-differently-dotted boolean? "
 405 Merge noteheads in collisions, even if they have a different number of
 406 dots. This normal notation for some types of polyphonic music. The
 407 value of this setting is used by @ref{note-collision-interface}
 408
 409 ")
 410     (elt-property-description 'note-width 'number? "unit for horizontal translation, measured in staff-space.")
 411     )   )  )
 412
 413
 414 (define custos-interface
 415   (lily-interface
 416    'custos-interface
 417    "A custos is a staff context symbol that appears at the end of a
 418   staff line with monophonic musical contents (i.e. with a single
 419   voice).  It anticipates the pitch of the first note of the following
 420   line and thus helps the player or singer to manage line breaks
 421   during performance, thus enhancing readability of a score.
 422
 423   Custodes were frequently used in music notation until the 16th
 424   century.  There were different appearences for different notation
 425   styles.  Nowadays, they have survived only in special forms of
 426   musical notation such as via the editio vaticana dating back to the
 427   beginning of the 20th century.
 428
 429 [TODO: add to glossary]"
 430
 431    (list
 432     (elt-property-description 'style string? "a string determining what glyph is
 433 typeset. Current choices are mensural,
 434 hufnagel, vaticana and medicaea [TODO: should use symbol] ")
 435     ))
 436   )
 437
 438
 439
 440 (define dot-interface
 441   (lily-interface
 442    'dots-interface
 443    "The dots to go with a notehead/rest.  A separate interface, since they
 444   are a party in collision resolution."
 445    (list
 446     (elt-property-description 'direction dir? "Direction to handle staff-line collisions in.")
 447     (elt-property-description 'dot-count integer? "number of dots")
 448     )))
 449
 450 (define font-interface
 451   (lily-interface
 452    'font-interface
 453    "Any symbol that is typeset through fixed sets of glyphs (ie. fonts)"
 454    (list
 455     (elt-property-description 'font-style symbol? "a precooked set of font definitions, eg. finger volta timesig mark script large Large dynamic")
 456     (elt-property-description 'font-series symbol? "partial font definition: medium, bold")
 457     (elt-property-description 'font-shape symbol?  "partial font definition: upright or italic")
 458     (elt-property-description 'font-family symbol? "partial font definition: music roman braces dynamic math ...")
 459     (elt-property-description 'font-name symbol? "partial font definition: base name of font file FIXME: should override other partials")
 460     (elt-property-description 'font-point-size number? "partial font definition: exact font size in points FIXME: should override font-relative-size")
 461     (elt-property-description 'font-relative-size number? "partial font definition: the relative size, 0 is style-sheet's normal size, -1 is smaller, +1 is bigger")
 462     )))
 463
 464
 465 (define text-interface
 466   (lily-interface
 467    'text-interface
 468    "A scheme markup text"
 469    (list
 470     (elt-property-description 'text (lambda (x) (or (string? x) (list? x))) "
 471 Scheme markup text.  It is defined as follows:
 472
 473 @example
 474
 475 TEXT : STRING | (MARKUP SENTENCE)
 476 MARKUP: PROPERTY | ABBREV
 477 SENTENCE: TEXT | SENTENCE TEXT
 478 PROPERTY: (key . value)
 479 ABBREV: rows lines roman music bold italic named super sub text, or any font-style
 480
 481 @end example
 482
 483 So, TEXT is either a string, or a list of which the CAR is a MARKUP.
 484 MARKUP is either a CONS: an element property '(key . value) or a symbol:
 485 a predefined abbreviation for a list of element properties.
 486
 487
 488 The following abbreviations are currently defined:
 489 @table @samp
 490 @item rows
 491 horizontal mode: set all text on one line (default)
 492 @item lines
 493  vertical mode: set every text on new line
 494 @item roman
 495  select roman font
 496 @item music
 497  select feta font
 498 @item bold
 499  select bold series
 500 @item italic
 501  select italic shape
 502 @item named
 503  lookup by character name
 504 @item text
 505  plain text lookup (by character value)
 506 @item super
 507  superscript
 508 @item sub
 509  subscript
 510 @item any font-style
 511  finger volta timesig mmrest mark script large Large dynamic
 512 @end table
 513 " )
 514     ;; Should move this somewhere else?
 515     (elt-property-description 'align number? "the alignment of the text, 0 is horizontal, 1 is vertical")
 516     (elt-property-description 'lookup symbol? "lookup method: 'value for plain text, 'name for character-name")
 517     (elt-property-description 'raise number? "height for text to be raised (a negative value lowers the text")
 518     (elt-property-description 'kern number? "amount of extra white space to add before text.  This is `relative'(?) to the current alignment.")
 519     (elt-property-description 'magnify number? "the magnification factor.  FIXME: doesn't work for feta fonts")
 520     )))
 521
 522 (define dot-column-interface
 523   (lily-interface
 524    'dot-column-interface
 525    "Interface that groups dots so they form a column"
 526    (list
 527     )))
 528
 529 (define dynamic-interface
 530   (lily-interface
 531    'dynamic-interface
 532    "Any kind of loudness sign"
 533    '()
 534     ))
 535
 536
 537 (define finger-interface
 538   (lily-interface
 539    'finger-interface
 540    "A fingering instruction"
 541    '()
 542     ))
 543
 544 (define separation-spanner-interface
 545   (lily-interface
 546    'separation-spanner-interface
 547    "Spanner that containing @code{separation-item-interface} elements to calculate rods"
 548    '()
 549   ))
 550 (define text-script-interface
 551   (lily-interface
 552    'text-script-interface
 553    "Any text script"
 554    '()
 555     ))
 556
 557 (define grace-alignment-interface
 558   (lily-interface
 559    'grace-alignment-interface
 560    "put grace notes in line"
 561    (list
 562     (elt-property-description 'horizontal-space number? "amount of space to add after a note (in staff-space)")
 563     )
 564    ))
 565
 566 (define hara-kiri-group-interface
 567   (lily-interface
 568    'hara-kiri-group-interface
 569    "  As Vertical_group_spanner, but keep track of interesting items.  If
 570   we don't contain any interesting items after linebreaking, then
 571   gracefully commit suicide.  Objective: don't disgrace Lily by
 572   typesetting empty lines in orchestral scores."
 573    (list
 574     (elt-property-description 'items-worth-living list? "list of interesting items. If empty in a particular system, clear that system.")
 575
 576
 577     )))
 578
 579 (define lyric-hyphen-interface
 580   (lily-interface
 581    'lyric-hyphen-interface
 582    "A centred hyphen is a simple line between lyrics used to divide
 583 syllables.   The length of the hyphen line should stretch based on the
 584   size of the gap between syllables."
 585    (list
 586
 587     (elt-property-description 'thickness number? "thickness of line (in stafflinethickness)")
 588     (elt-property-description 'height number? "vertical offset  (in staffspace)")
 589
 590     (elt-property-description 'minimum-length number? "try to make the hyphens at least this long. Also works as a scaling parameter for the length")
 591     (elt-property-description 'word-space number? "elongate left by this much (FIXME: cumbersome semantics)")
 592     )))
 593
 594 (define key-signature-interface
 595   (lily-interface
 596    'key-signature-interface
 597    "A group of  accidentals."
 598    (list
 599     (elt-property-description 'c0-position  integer? "integer indicating the position of central C")
 600     (elt-property-description 'old-accidentals  list? "list of (pitch, accidental) pairs")
 601     (elt-property-description 'new-accidentals  list? "list of (pitch, accidental) pairs")
 602     )))
 603
 604 (define lyric-extender-interface
 605   (lily-interface
 606    'lyric-extender-interface
 607    "The extender is a simple line at the baseline of the lyric
 608   that helps show the length of a melissima (tied/slurred note)."
 609    (list
 610     (elt-property-description 'word-space  number? "")
 611     (elt-property-description 'height  number? "in stafflinethickness")
 612     (elt-property-description 'right-trim-amount  number? "")
 613     )))
 614
 615
 616 (define lyric-syllable-interface
 617   (lily-interface
 618    'lyric-syllable-interface
 619    "a single piece of lyrics"
 620    (list
 621     (elt-property-description 'word-space  number? "")
 622     )))
 623
 624
 625 (define mark-interface
 626   (lily-interface
 627    'mark-interface
 628    "a rehearsal mark"
 629    (list
 630     )))
 631
 632 (define multi-measure-rest-interface
 633   (lily-interface
 634    'multi-measure-rest-interface
 635    "A rest that spans a whole number of measures.  For typesetting the
 636 numbers, fields from font-interface may be used.
 637 "
 638    (list
 639
 640     (elt-property-description 'columns  list? "list of paper-columns")
 641     (elt-property-description 'expand-limit  integer? "maximum number of measures expanded in church rests")
 642     (elt-property-description 'minimum-width number? "minimum-width of rest symbol, in staffspace")
 643     (elt-property-description 'padding  number? "padding between number and rest. Measured in staffspace.")
 644     )))
 645
 646 (define paper-column-interface
 647   (lily-interface
 648    'paper-column-interface
 649    ""
 650    (list
 651     (elt-property-description 'column-space-strength number? "relative strength of space following breakable columns (eg. prefatory matter)")
 652     (elt-property-description 'before-musical-spacing-factor number?
 653 "space before musical columns (eg. taken by accidentals) get this much
 654 stretched when they follow a musical column, in absence of grace
 655 notes.  0.0 means no extra space (accidentals are ignored)")
 656     (elt-property-description 'stem-spacing-correction number? "optical correction amount.")
 657     (elt-property-description 'before-grace-spacing-factor number? " stretch space this much if there are grace notes before the column")
 658     (elt-property-description 'when moment? "when does this column happen?")
 659     (elt-property-description 'bounded-by-me list? "list of spanners that have this
 660 column as start/begin point. Only columns that have elements or act as bounds are spaced.")
 661     (elt-property-description 'dir-list  list? "list of stem directions")
 662     (elt-property-description 'shortest-playing-duration  moment? "duration of the shortest playing in that column.")
 663     (elt-property-description 'shortest-starter-duration  moment? "duration of the shortest notes that starts exactly in this column.")
 664     (elt-property-description 'contains-grace  boolean? "Used to widen entries for grace notes.")
 665     (elt-property-description 'extra-space  number-pair? "pair of distances")
 666     (elt-property-description 'stretch-distance number-pair? "pair of distances")
 667     )))
 668
 669 (define spaceable-element-interface
 670   (lily-interface
 671    'spaceable-element-interface
 672    "An element (generally a Paper_column) that takes part in the
 673 spacing problem. "
 674    (list
 675      (elt-property-description 'minimum-distances list? "list of rods (ie. (OBJ . DIST) pairs)")
 676      (elt-property-description 'ideal-distances  list? "(OBJ . (DIST . STRENGTH)) pairs")
 677      (elt-property-description 'dir-list list? "list of stem directions, needed for optical spacing correction.")
 678      )))
 679
 680 (define rest-collision-interface
 681   (lily-interface
 682    'rest-collision-interface
 683    "Move around ordinary rests (not multi-measure-rests) to avoid
 684 conflicts."
 685    (list
 686     (elt-property-description 'maximum-rest-count integer? "kill off rests so we don't more than this number left.")
 687     (elt-property-description 'minimum-distance number? "minimum distance between notes and rests.")
 688     (elt-property-description 'elements list? "list of elements (NoteColumn,
 689 generally) participating in the collision. The
 690 @code{rest-collision} property in @code{elements} is set
 691 to a pointer to the collision")
 692     )))
 693
 694 (define script-interface
 695   (lily-interface
 696    'script-interface
 697    ""
 698    (list
 699     (elt-property-description 'script-priority number? "A sorting key that determines in what order a script is within a stack of scripts")
 700     )))
 701
 702 (define script-column-interface
 703   (lily-interface
 704    'script-column-interface
 705    "An interface that sorts scripts according to their @code{script-priority}"
 706    (list )))
 707
 708
 709 (define spacing-spanner-interface
 710   (lily-interface
 711    'spacing-spanner-interface
 712    ""
 713    (list
 714     (elt-property-description 'maximum-duration-for-spacing moment? "space as if a duration of this type is available in this measure.")
 715     (elt-property-description 'arithmetic-basicspace number? "The space taken by a note is determined by the formula
 716
 717    SPACE = arithmetic_multiplier * ( C + log2 (TIME) ))
 718
 719 where TIME is the amount of time a note occupies.  The value of C is
 720 chosen such that the smallest space within a measure is
 721 arithmetic_basicspace:
 722
 723   C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8))
 724
 725 The smallest space is the one following the shortest note in the
 726 measure, or the space following a hypothetical 1/8 note.  Typically
 727 arithmetic_basicspace is set to a value so that the shortest note
 728 takes about two noteheads of space (ie, is followed by a notehead of
 729 space):
 730
 731 @example
 732    2*quartwidth = arithmetic_multiplier * ( C + log2 (SHORTEST) ))
 733
 734    @{ using: C = arithmetic_basicspace - log2 (mininum (SHORTEST, 1/8)) @}
 735    @{ assuming: SHORTEST <= 1/8 @}
 736
 737                = arithmetic_multiplier *
 738                ( arithmetic_basicspace - log2 (SHORTEST) + log2 (SHORTEST) )
 739
 740                = arithmetic_multiplier * arithmetic_basicspace
 741
 742    @{ choose: arithmetic_multiplier = 1.0*quartwidth (why?) @}
 743
 744                = quartwidth * arithmetic_basicspace
 745
 746    =>
 747
 748    arithmetic_basicspace = 2/1 = 2
 749
 750
 751 If you want to space your music wider, use something like:
 752
 753    arithmetic_basicspace = 4.;
 754
 755 @end example
 756 ")
 757     (elt-property-description 'arithmetic-multiplier number? "see arithmetic-basicspace")
 758
 759     )))
 760
 761 (define staff-symbol-interface
 762   (lily-interface
 763    'staff-symbol-interface
 764    "This spanner draws the lines of a staff.  The middle line is
 765 position 0."
 766    (list
 767     (elt-property-description 'staff-space number? "Amount of line leading relative to global staffspace")
 768     (elt-property-description 'line-count integer? "Number of staff lines")
 769     )))
 770
 771 (define stem-tremolo-interface
 772   (lily-interface
 773    'stem-tremolo-interface
 774    ""
 775    (list
 776     (elt-property-description 'stem ly-element? "pointer to the stem object.")
 777     (elt-property-description 'beam-width number? "width of the tremolo sign")
 778     (elt-property-description 'beam-thickness number? "thickness, measured in staffspace")
 779     (elt-property-description 'beam-space-function procedure? "function returning space given multiplicity")
 780     )))
 781
 782 (define separation-item-interface
 783   (lily-interface
 784    'separation-item-interface
 785    "Item that computes widths to generate spacing rods.
 786
 787 Calc dimensions for the Separating_group_spanner; this has to be
 788    an item to get dependencies correct.  It can't be an element_group
 789    since these usually are in a different X_group
 790 "
 791    (list
 792     (elt-property-description 'elements list? " -- list of items.")
 793      )))
 794
 795 (define sustain-pedal-interface
 796   (lily-interface
 797    'sustain-pedal-interface
 798    ""
 799    (list
 800     )))
 801 (define system-start-delimiter
 802   (lily-interface
 803    'system-start-delimiter
 804    ""
 805    (list
 806     (elt-property-description 'collapse-height number? "")
 807     (elt-property-description 'thickness number? "thickness, measured in stafflinethickness")
 808
 809     ; Should collapse into (bracket . ((height . ) ... ))
 810     ;
 811     (elt-property-description 'arch-height number? "")
 812     (elt-property-description 'arch-angle number? "")
 813     (elt-property-description 'arch-thick number? "")
 814     (elt-property-description 'arch-width number? "")
 815     (elt-property-description 'bracket-thick number? "")
 816     (elt-property-description 'bracket-width number? "")
 817     (elt-property-description 'glyph symbol? "bar-line, bracket or brace")
 818     )))
 819
 820 (define text-spanner-interface
 821   (lily-interface
 822    'text-spanner-interface
 823    "generic text spanner"
 824    (list
 825     (elt-property-description 'dash-period  number? "the length of one dash + white space")
 826     (elt-property-description 'dash-length number? "the length of a dash")
 827     (elt-property-description 'line-thickness number? "the thickness[stafflinethickness] of the line")
 828     (elt-property-description 'edge-height pair? "a cons that specifies the heights of the vertical egdes '(LEFT-height . RIGHT-height)")
 829     (elt-property-description 'edge-text pair? "a cons that specifies the texts to be set at the edges '(LEFT-text . RIGHT-text)")
 830     (elt-property-description 'type string? "one of: line, dashed-line or dotted-line") ; SYMBOL!!?
 831     )
 832 ))
 833
 834 (define tie-interface
 835   (lily-interface
 836    'tie-interface
 837    "A tie connecting two noteheads."
 838    (list
 839     (elt-property-description 'staffline-clearance number? "don't get closer than this to stafflines.")
 840     (elt-property-description 'control-points list? "List of 4 offsets (number-pairs) controlling the tie shape")
 841     (elt-property-description 'heads pair? "pair of element pointers, pointing to the two heads of the  tie. ")
 842     (elt-property-description 'details list? "alist of parameters for the curve shape")
 843     (elt-property-description 'thickness number? "thickness, measured in stafflinethickness")
 844     (elt-property-description 'x-gap number? "horizontal gap between notehead and tie")
 845     (elt-property-description 'direction dir? "up or down?")
 846     (elt-property-description 'minimum-length number? "minimum length in staffspace")
 847     )))
 848
 849
 850
 851 (define tie-column-interface
 852   (lily-interface
 853    'tie-column-interface
 854    "that sets tie directions in a tied chord"
 855    (list
 856     (elt-property-description 'direction dir? "Forced direction for all ties")
 857     )))
 858
 859 (define volta-bracket-interface
 860   (lily-interface
 861    'volta-bracket-interface
 862    "Volta bracket with number"
 863    (list
 864     (elt-property-description 'bars  list? "list of barline ptrs.")
 865     (elt-property-description 'thickness  number? "thickness, measured in stafflinethickness")
 866     (elt-property-description 'height  number? "in staffspace ")
 867     )))
 868
 869 (define span-bar-interface
 870   (lily-interface
 871    'span-bar-interface
 872    ""
 873    (list
 874     )))
 875