anchor.diff:  DOCUMENTATION is the documentation string for the function.
   
   Example:
  -;; (define-event-special-key amp (:db (db-amp (raw-event-value event :db))
  -;;                                 t 0.5)
  +;; (define-event-special-key amp ((:db (db-amp (raw-event-value event :db)))
  +;;                                (t 0.5))
   ;;   :define-methods t)
   
   This defines the amp key for events. Since the :amp KEY is implied, it doesn't need to be specified in the CASES. Thus if the event already has an :amp key, its value will be used by default. If no :amp key exists in the event, then the :db FUNC is run if the :db key exists. If neither :amp nor :db exist in the event, then the t key is run, giving a default of 0.5.
  
positive.code: (defmacro define-event-special-key (name cases &key (remove-keys t) (define-methods nil) documentation)
    "Define a special key with the key NAME for events (i.e. keys that take their values from other keys, or keys that have default values).
  
  CASES is a plist of cases mapping event key names to forms. When `event-value' is called on an event for the NAME key, then the event is tested for the keys of CASES in the order they're listed. The associated form of the first key of CASES that exists in the event is evaluated to get the value of that call to `event-value'.
  
  If no case is provided with a key that's the same as NAME, one is automatically added at the start with a form that just returns the value of the event's NAME key. If a case is provided with t as its key, that case is always run when found. This allows you to set a default value for the key if none of the other keys from CASES exist in the event.
  
  
negative.code: 
  ;;; timing
  
  (define-event-special-key timing-offset ((t 0)))
  
  (define-event-special-key quant ((:quant (ensure-list (raw-event-value event :quant)))
                                   (t (list 1)))
    :define-methods t)
  
  ;;; pitch
  
  (define-event-special-key freq ((:midinote (midinote-freq (event-value event :midinote)))
                                  (:degree (degree-freq (event-value event :degree)
                                                        :root (event-value event :root)
                                                        :octave (event-value event :octave)
                                                        :scale (event-value event :scale)))
                                  (t 440))
    :remove-keys (:midinote :degree :root :octave)
    :define-methods t
    :documentation "Frequency of the note, in Hz.
  
  See also: `rate', `midinote', `degree'")
  
  (define-event-special-key midinote ((:freq (freq-midinote (event-value event :freq)))
                                      (:degree (degree-midinote (event-value event :degree)
                                                                :root (event-value event :root)
                                                                :octave (event-value event :octave)
                                                                :scale (event-value event :scale)))
                                      (t 69))
    :remove-keys (:freq :degree :root :octave)
    :define-methods t
    :documentation "MIDI note number of the note (0-127).")
  
  ;; FIX: this can return NIL. i.e. (degree (event :midinote 0))
  (define-event-special-key degree ((:freq (midinote-degree (freq-midinote (event-value event :freq))
                                                            :root (event-value event :root)
                                                            :octave (event-value event :octave)
                                                            :scale (event-value event :scale)))
                                    (:midinote (midinote-degree (event-value event :midinote)
                                                                :root (event-value event :root)
                                                                :octave (event-value event :octave)
                                                                :scale (event-value event :scale)))
                                    (t 5))
    :remove-keys (:freq :midinote))
  
  (define-event-special-key root ((t 0)) ;; FIX: can we derive this when :freq, :midinote, :degree, etc are available?
    :remove-keys (:freq :midinote))
  
  (define-event-special-key octave ((:freq (freq-octave (raw-event-value event :freq)))
                                    (:midinote (midinote-octave (raw-event-value event :midinote)))
                                    (t 5))
    :remove-keys (:freq :midinote))
  
  (define-event-special-key scale ((t :major))
    :remove-keys (:freq :midinote)
    :define-methods t)
  
  (define-event-special-key base-freq ((:base-note (midinote-freq (event-value event :base-note)))
                                       (t 440)))
  
  (define-event-special-key base-note ((:base-freq (freq-midinote (event-value event :base-freq)))
                                       (t 69)))
  
  (define-event-special-key rate ((t (let ((res (multiple-value-list (event-value event :freq))))
                                       (values (freq-rate (car res) (event-value event :base-freq))
                                               (cadr res)))))
    ;; we don't do remove-keys because other frequency keys are not exact synonyms.
    ;; it's also conceivable that some instruments may use both :rate and :freq.
    :define-methods t
  