scm/define-music-properties.scm

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