# -*- fill-column: 78 -*-

* Overview

  The configuration is distributed among various files and directories.

  Technical Config:
  
  - config.yaml :: Main config file; see comments within for some
    explanations.

  - ~/harpwise/config.yaml :: Optional, may contain any of
    the config-keys from config.yaml and then overrides those; not included in
    git-versioning.

  - intervals.yaml :: Names for selected intervals.


  Each type of harmonica (e.g. richter) has a directory with its own 
  Musical Config:

  - intervals.yaml :: If this file is present within a subdirectory, it
    overrides the one directly within config.

  - holes.yaml :: Maps holes to notes for a harmonica of key c. Any other key
    (chosen when starting the harpwise) will be automatically derived from this
    one

  - scales_SCALE_with_holes.yaml :: List of holes for scale SCALE; each line
    should contain a hole name, as given in holes.yaml.
  
    On each line, after the note (and a space), you may add arbitrary text,
    that will be displayed as a remark (see the section on display); the
    special word 'root' marks a root note, which will be favored in quiz.

  - scales_SCALE_with_notes.yaml :: List of notes for scale SCALE. Accepts a
    remark too.

  
  Each scale (e.g. blues or major_pentatonic) has its own file and can be
  either notated with holes or notes, but NOT both. However, if a scale with
  notes is parsed, the same scale is written out with holes (prefixed with the
  word 'derived') and vice versa. So for example using
  scale_blues_with_holes.yaml will trigger the creation of
  derived_scale_blues_with_notes.yaml (within ~/harpwise/derived)

* Creating new scales for a given type

  E.g. for a new scale chord-iii (notes from the iii-chord), you would just
  copy the file scales_all_with_holes.yaml (see above) to
  scales_chord-iii_with_holes.yaml and edit it appropriately. The next time,
  the harpwise is started, it would recognize the new scale.

  Creating new scales is easy and should be used freely to support your
  training.

* Creating a new type of harmonica

  (Please also read the section "A word on holes" from the toplevel README.org too)

  You may create a new type of harmonica (e.g. country-tuning) by copying one of
  the existing dirs (e.g. richter) to a new name (country) and modify the
  contained files accordingly.

  In this process you may remove some of the copied scale-files and rename
  some of the derived scale-files to remove the prefix 'derved_'; this way you
  can choose which scales you want to have for your new type of harmonica, and
  how you want to notate these scales (with holes or with notes).

  Let error messages be your guide in this process.

  Also note, that the hole-names (e.g. "-1") used throughout the configuration
  files are more or less customary and can be chosen at will; they only need
  to be consistent within one type of harmonica (e.g richter). A different
  type (e.g. chromatic) may use totally or partially different names for holes
  (e.g. "-1b").

  The note-names (e.g. "a4" or gs5) on the other hand follow a strict schema,
  from which you may not deviate.
