scm/define-music-properties.scm

   1 ;;;; define-music-properties.scm -- part of generated backend documentation
   2 ;;;;
   3 ;;;;  source file of the GNU LilyPond music typesetter
   4 ;;;;
   5 ;;;; (c) 1998--2009  Han-Wen Nienhuys <hanwen@xs4all.nl>
   6 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
   7
   8 (define (music-property-description symbol type? description)
   9   (if (not (equal? #f (object-property symbol 'music-doc)))
  10       (ly:error (_ "symbol ~S redefined") symbol))
  11   (set-object-property! symbol 'music-type? type?)
  12   (set-object-property! symbol 'music-doc description)
  13   symbol)
  14
  15 (define-public all-music-properties
  16   (map
  17    (lambda (x) (apply music-property-description x))
  18    `(
  19      (absolute-octave ,integer?
  20                       "The absolute octave for a octave check note.")
  21      (alteration ,number? "Alteration for figured bass.")
  22      (articulation-type ,string? "Key for script definitions alist.
  23
  24 TODO: Consider making type into symbol.")
  25      (articulations ,ly:music-list?
  26                     "Articulation events specifically for this note.")
  27      (associated-context ,string? "Name of the Voice context associated with
  28 this @code{\\lyricsto} section.")
  29      (augmented ,boolean? "This figure is for an augmented figured bass
  30 (with @code{+} sign).")
  31      (augmented-slash ,boolean? "This figure is for an augmented figured bass
  32 (back-slashed number).")
  33
  34      (bass ,boolean? "Set if this note is a bass note in a chord.")
  35      (bracket-start ,boolean? "Start a bracket here.
  36
  37 TODO: Use SpanEvents?")
  38      (bracket-stop ,boolean? "Stop a bracket here.")
  39      (break-penalty ,number? "Penalty for line break hint.")
  40      (break-permission ,symbol?
  41                        "Whether to allow, forbid or force a line break.")
  42
  43      (cautionary ,boolean? "If set, this alteration needs a
  44 cautionary accidental.")
  45      (change-to-id ,string? "Name of the context to change to.")
  46      (change-to-type ,symbol? "Type of the context to change to.")
  47      (compress-procedure ,procedure? "Compress this music expression.
  48 Arg@tie{}1: the music, arg@tie{}2: factor.")
  49      (context-id ,string? "Name of context.")
  50      (context-type ,symbol?  "Type of context.")
  51      (create-new ,boolean? "Create a fresh context.")
  52
  53      (delta-step ,number? "How much should a fall change pitch?")
  54      (denominator ,integer? "Denominator in a time signature.")
  55      (descend-only ,boolean? "If set, this @code{\\context} only descends
  56 in the context tree.")
  57      (digit ,integer? "Digit for fingering.")
  58      (diminished ,boolean? "This bass figure should be slashed.")
  59      (direction ,ly:dir? "Print this up or down?")
  60      (drum-type ,symbol? "Which percussion instrument to play this note on.")
  61      (duration ,ly:duration? "Duration of this note or lyric.")
  62
  63      (element ,ly:music? "The single child of a Music_wrapper music object,
  64 or the body of a repeat.")
  65      (elements ,ly:music-list? "A list of elements for sequential of
  66 simultaneous music, or the alternatives of repeated music.")
  67      (elements-callback ,procedure? "Return a list of children, for use by
  68 a sequential iterator.  Takes a single music parameter.")
  69      (error-found ,boolean?
  70                   "If true, a parsing error was found in this expression.")
  71
  72      (figure ,integer? "A bass figure.")
  73      (force-accidental ,boolean? "If set, a cautionary accidental should
  74 always be printed on this note.")
  75
  76      (grob-property ,symbol? "The symbol of the grob property to set.")
  77      (grob-property-path ,list? "A list of symbols, locating a nested grob
  78 property, e.g., @code{(beamed-lengths details)}.")
  79      (grob-value ,scheme? "The value of the grob property to set.")
  80
  81      (input-tag ,scheme? "Arbitrary marker to relate input and output.")
  82      (inversion ,boolean? "If set, this chord note is inverted.")
  83      (iterator-ctor ,procedure? "Function to construct a
  84 @code{music-event-iterator} object for this music.")
  85
  86      (label ,markup? "Label of a mark.")
  87      (last-pitch ,ly:pitch? "The last pitch after relativization.")
  88      (length ,ly:moment? "The duration of this music.")
  89      (length-callback ,procedure? "How to compute the duration of this music.
  90 This property can only be defined as initializer in
  91 @file{scm/@/define-music-types.scm}.")
  92      (line-break-permission ,symbol? "When the music is at top-level,
  93 whether to allow, forbid or force a line break.")
  94
  95      (metronome-count ,number? "How many beats in a minute?")
  96
  97      (name ,symbol? "Name of this music object.")
  98      (no-continuation ,boolean? "If set, disallow continuation lines.")
  99      (numerator ,integer? "Numerator of a time signature.")
 100
 101      (octavation ,integer? "This pitch was octavated by how many octaves?
 102 For chord inversions, this is negative.")
 103      (once ,boolean? "Apply this operation only during one time step?")
 104      (origin ,ly:input-location? "Where was this piece of music defined?")
 105
 106      (page-break-permission ,symbol? "When the music is at top-level,
 107 whether to allow, forbid or force a page break.")
 108      (page-label ,symbol? "The label of a page marker.")
 109      (page-marker ,boolean? "If true, and the music expression is found at
 110 top-level, a page marker object is instanciated instead of a score.")
 111      (page-turn-permission ,symbol? "When the music is at top-level,
 112 whether to allow, forbid or force a page turn.")
 113      (parenthesize ,boolean? "Enclose resulting objects in parentheses?")
 114      (part-combine-status ,symbol? "Change to what kind of state?
 115 Options are @code{solo1}, @code{solo2} and @code{unisono}.")
 116      (pitch ,ly:pitch? "The pitch of this note.")
 117      (pitch-alist ,list? "A list of pitches jointly forming the scale
 118 of a key signature.")
 119      (pop-first ,boolean? "Do a revert before we try to do a override
 120 on some grob property.")
 121      (prob-property ,symbol? "The symbol of the prob property to set.")
 122      (procedure ,procedure? "The function to run with @code{\\applycontext}.
 123 It must take a single argument, being the context.")
 124      (property-operations ,list? "Do these operations for instantiating
 125 the context.")
 126
 127      (quoted-context-id ,string? "The ID of the context to direct quotes to,
 128 e.g., @code{cue}.")
 129      (quoted-context-type ,symbol? "The name of the context to
 130 direct quotes to, e.g., @code{Voice}.")
 131      (quoted-events ,vector? "A vector of with @code{moment} and
 132 @code{event-list} entries.")
 133      (quoted-music-name ,string? "The name of the voice to quote.")
 134      (quoted-transposition ,ly:pitch? "The pitch used for the quote,
 135 overriding @code{\\transposition}.")
 136      (quoted-voice-direction ,ly:dir? "Should the quoted voice be up-stem
 137 or down-stem?")
 138
 139      (repeat-count ,integer? "Do a @code{\\repeat} how often?")
 140
 141      (span-direction ,ly:dir? "Does this start or stop a spanner?")
 142      (span-type ,string? "What kind of spanner should be created? E.g. ligature
 143 for ligatures, or text or hairpin for (de-)crescendi.
 144
 145 TODO: Consider making type into symbol.")
 146      (span-text ,string? "The displayed text for text spanners (e.g. cresc.)")
 147      (split-list ,list? "Splitting moments for part combiner.")
 148      (start-callback ,procedure? "Function to compute the negative length
 149 of starting grace notes.  This property can only be defined as initializer
 150 in @file{scm/@/define-music-types.scm}.")
 151      (string-number ,integer? "The number of the string in
 152 a @code{StringNumberEvent}.")
 153      (symbol ,symbol? "Grob name to perform an override or revert on.")
 154
 155      (tags ,list? "List of symbols that for denoting extra details, e.g.,
 156 @code{\\tag #'part @dots{}} could tag a piece of music as only being active
 157 in a part.")
 158      (tempo-unit ,ly:duration? "The unit for the metronome count.")
 159      (text ,markup? "Markup expression to be printed.")
 160      (text-type ,symbol?
 161                 "Particular type of text script (e.g., finger, dynamic).")
 162      (to-relative-callback ,procedure? "How to transform a piece of music
 163 to relative pitches.")
 164      (tonic ,ly:pitch? "Base of the scale.")
 165      (tremolo-type ,integer? "Speed of tremolo, e.g., 16 for @code{c4:16}.")
 166      (trill-pitch ,ly:pitch? "Pitch of other note of the trill.")
 167      (tweaks ,list? "An alist of properties to override in the backend
 168 for the grob made of this event.")
 169      (type ,symbol? "The type of this music object.
 170 Determines iteration in some cases.")
 171      (types ,list? "The types of this music object; determines by what
 172 engraver this music expression is processed.")
 173
 174      (untransposable ,boolean? "If set, this music is not transposed.")
 175
 176      (value ,scheme? "Assignment value for a translation property.")
 177      (void ,boolean? "If this property is @code{#t}, then the
 178 music expression is to be discarded by the toplevel music handler.")
 179
 180      (what ,symbol? "What to change for auto-change.
 181
 182 FIXME: Naming.")
 183
 184      (X-offset ,number?
 185                "Offset of resulting grob; only used for balloon texts.")
 186
 187      (Y-offset ,number?
 188                "Offset of resulting grob; only used for balloon texts.")
 189     )))