abcde interfaces
================

abcde uses a lot of files as it runs in order to keep track of current
status and to store the various bits of data it's using, like cddb
lookups and results, user choices, encoding etc.

Here is (the start of!) a quick guide to what each file is used
for. Each file lives in $ABCDETEMPDIR at runtime, which is the
per-disc working directory that abcde uses. Once the "clean" operation
has happened, they all go away.

CD lookups
----------

cddbchoices - concatenation of all the lookups with some status
              information. Displayed to the user once all the lookups
              are complete, as the list of results to choose from.

cddbread.X -  generic-ish results from a disc lookup, for match number
              X. Based on the format used by *cddb*, but the
              musicbrainz and cdtext lookup methods have been written
              to (roughly) output this format as an interface so the
              rest of the abcde code doesn't need massive adaptation
              to new formats. Match number 0 is special - it's a blank
              template file ready for the user to edit in case there's
              no correct match.

datasource.X- text label for the source of the data in cddbread.X,
	      e.g. "cddb" or "Musicbrainz". Generated by the data
	      lookup methods, then used later if we care where the
	      data came from.

cddbquery.X - Summary of a single disc lookup result. Based on the
	      complicated format used by *cddb*, but without the
	      result code. Generated by the data lookup methods, then
	      used later to fabricate a composite cddbquery file.

cddbquery   - result code and summary of a disc lookup. Based on the
	      format used by *cddb*, and faked up by the other lookup
	      methods. A single successful match will look like:

	      200 $genre $discid $artist / $album

	      Multiple successful matches will show up as

	      210 Found exact matches, list follows (until terminating `.')
	      $genre1 $discid $artist1 / $album1
	      $genre2 $discid $artist2 / $album2
	      .

	      Other response codes are possible, 999 is special and
	      used internally by abcde to denote a local cddb data
	      cache

cue-<discid>.txt - cue file generated from the track data on the disc

cddbdiscid  - raw data showing the cddb discid and the track info numbers
	      used to calculate it

mbdiscid    - raw data showing a musicbrainz discid and the track info
	      numbers used to calculate it

status 	    - log file of all the operations carried out thus far. Format
	      is important - things are looked up here regularly to
	      work out what's happened and what should be done
	      next. See usage of the checkstatus() function to look
	      for things.

Files specific to lookups using *cddb*, in the data-cddb subdir:

 * cddbstat - status from a cddb server, downloaded as a check that
              the server is working correctly (ish!)

Files specific to lookups using *musicbrainz*:

 * asin.X   -\ details about musicbrainz-specific information for
 * mbid.X   -/ match number X.

specific to lookups using *cdtext*, in the data-cdtext subdir:

 * cd-text  - the raw CD-Text information as returned by icedax/cdda2wav

...

More to follow...?
