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