This document gives an idea about the new DB structure and the way to
operate it. The new DB is neither compatible with workman-style data base
used in previous sadp releases, nor with any other DB structure. However
the application provides a read-only access to workman data base to allow
data transfer. See section: ACCESS TO OTHER DATA BASES below.

CONTENT:  YOU MAY ASK ...
	  ADVANTAGES OF THE NEW sadp CD DATA BASE.            
	  STRUCTURE OF THE DATA BASE.
	  OPERATING THE DATA IN APPLICATION.	
	  ACCESS TO OTHER DATA BASES.


YOU MAY ASK ...
^^^^^^^^^^^^^^^

Why another DB structure was needed ?
=====================================
- Workman keeps data in a plane text file. If the disc information is
  located near the end, the whole data base has to be scanned in order
  to find the data. 

- Dirk Foersterling, the current workman maintainer introduced a number
  of great features into the DB structure. Some of those (information
  vs preferences, skiplists) influenced the new sadp DB design, however
  others do not quite consistent with sadp design.

- As the result of innovations mentioned before, old sadp data base lost
  its compatibility with workman DB anyway. 


Why a new DB structure ?
========================
- I am simply unaware of any existing data structure that
  provides all the features described below. 


ADVANTAGES OF THE NEW sadp CD DATA BASE.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Fast access to data.
  Each disc information is kept in a separate file.

- Compression features. Data can be stored in uncompressed or compressed
  way using your favorite compression utility.

- Different preference sets for a given disc. Allows to share same disc
  information between different users, each having own preferred tracks
  or have several preference sets for a single user.

- Tolerance to unknown information. If the application encounters a
  comment, unknown keyword or section, it simply leaves it intact.
  Therefore if you decide to use this structure in your own application,
  feel free to enter new sections and keywords - this should not upset
  sadp. At the same time, this will allow sharing DB between current and
  future versions of sadp without damage to each other. This feature is
  not quite thoroughly tested - don't hesitate to contact me in case of
  surprises, or even if everything is OK - I might wish to implement the
  added features with sadp.


STRUCTURE OF THE DATA BASE.
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Up to two directories can be located for the data: a local (for
each user) and common (shared by all users). The paths are specified
by  DEFAULT_DB_PATH and DEFAULT_DB_ALTPATH parameters in sadp_config.h,
where the DEFAULT_DB_ALTPATH can be set to empty sting to indicate the
absence of common data base. Default locations:  ~/.sadp for local DB
and ${prefix}/share/sadp for common DB with ${prefix} as specified for
'configure' (default: /usr/local). If these settings are accepted, the
local DB path will keep all other files related to sadp (resources,
text-mode configuration, log file etc.)


The file name is selected as the following:

Medium Catalog Number (MCN)
   is enabled and present:  DU_mcn.ZZZ[.suffix] 

               Otherwise:  DI_cdindex.ZZZ[.suffix]

where 'mcn' stands for Medium Catalog Number, 'cdindex' refers to
the hash value used by CD-INDEX data base (see sadp man page for
RCDDB description), suffix corresponds to compression utility used
(no suffix for an uncompressed file). ZZZ is normally 000 - needed
to allow having possible clashes in the futures (i.e duplication
of MCN or CD-INDEX).
+----------------------------------------------------------------+
| N.B!  MCN (if applicable) AND CD-INDEX VALUES ARE SHOWN ON THE |
|       'Upload' FORM. (Select Cancel to avoid submission).      |
+----------------------------------------------------------------+

Examples of file names:
	   DU_1234567890123.000
	   DI_NnbSmyoedPdD3kxHbmrXDIlH760-.000.gz 

N.B. MCN support is disabled by default, because some disc drives
don't handle it properly. Don't enable it unless absolutely sure.
If MCN support is compiled with the code, it still can be disabled
by a command line argument:  'sadp -Om'  or  'xsadp -nomcn'.

The support of the following compression utilities is provided:
gzip (.gz) - factory default, bzip2 (.bz2), compress (.Z). You
can easily add a new compressor to the table: see comments in
sadp_sdbase.c

Since the compression format is established according to the suffix,
you can mix differently compressed data: the original compression
format will be preserved when editing data while the default format
is applied to the new entries only. The default format is specified
by DEFAULT_ZIP_TYPE parameter in sadp_config.h

If two paths are used, the local path has preference, however
if the file is found in the common path, it will be edited there,
without making a local copy. The new entry is always stored in the
local path - it needs to be copied to the common place.

Each entry consists of sections and lines. Currently recognized
sections are GENERAL(single), DISC(single), TRACKS(single),
PREFSET (several allowed). Comments start with a hash (#), or
can be located in a separate COMMENT section.

Track start is specified as the logical block address incremented
by MSF_OFFSET (150). The OWNER word contains an encrypted name for
the user who created the preference set. When application starts,
it will try to load the preference set created by the current user,
if fails - the first preference set is loaded. The meaning of other
keywords appears to be easily understood.


OPERATING THE DATA IN APPLICATION.	
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Data panels looks similar for text and GUI modes. In text mode the
"EXTRA" line is not shown for less than 28 lines screen resolution.

You can define the disc as a single or multiple artist using MULT/SNGL
button located next to disc title. For a single artist disc, the artist
name can be specified for the whole disc only and refers to all tracks. 
On the contrary, multiple artist disc accepts artist name for the whole
disc as well as for each separate track. Use DISC/TRCK button located
next to artist name to specify which artist information is entered. In
DISC position the information stays with changing tracks, while in TRCK
mode it varies between tracks. A similar toggle exists for EXTRA information
(composer, copyright, date, etc), however extra information can be track
specific also for a single artist disc.

PLAY/SKIP button next to track name, when pressed (SKIP is displayed)
specifies that current track has to be bypassed in normal and intro modes,
and avoided in random mode. However it will be played as a part of play list or if clicked in track list while in "integrated mode" (see man page).
The set of all skipped tracks is referred as "skip list" and is specific
to selected preference set.

Preference sets.
================

While disc information (single/multi, title, names and extra info) 
provide an "objective" disc characteristics, other features are determined
by the user, and can be characterised as preferences. This data base
can store several preference sets ('prefsets' for short) for a particular
disc.

Currently a prefset stores play lists and skip lists. Each prefset has a
name that you can type in. To change current prefset use arrow buttons. 

The last preference set is always empty. It is not stored, but allows
adding prefsets: when a track is added to the play list in the last prefset,
the new empty prefset is created (therefore the current prefset will no
longer be the last one).

In order to delete a prefset, remove all tracks from its play list (skip
list can still be non-empty). Press "Save". This will save data and update
the prefsets. Since prefsets with empty play lists are not stored, all
empty prefsets, apart from the last one, will be removed from the list.


ACCESS TO OTHER DATA BASES.
^^^^^^^^^^^^^^^^^^^^^^^^^^^

sadp-3 provides read-only access to old sadp data base, which represents
a minor extension to the old-style workman data base.

A new feature of sadp-3 is the ability to retrieve some information from
the extended workman data base.

The access is read-only and optional: you can easily exclude it from the
code (and save few K) if you are not going to use workman or old sadp DB.

The file name for old sadp or workman data base is specified by
DEFAULT_WDB_NAME parameter in sadp_config.h  If the definition is omitted
(commented out), the support will be excluded from the code.

Typical values of DEFAULT_WDB_NAME

	~/.xcddbase  - for xcd or old sadp data base (factory default)
	~/.workmandb - for true workman data base


Transferring the data from the old sadp DB.
==========================================

Unfortunately the old DB does not store all information needed for
CD identification, therefore a single pass converter can't be written.

However, with sadp-3 the data can be transfered with the following simple
procedure:

- Start sadp  or xsadp  with "auto-save data" option:  

	sadp    -OD
	xsadp   -savedata

- Load the CD into the tray: this will bring information from the old DB.
- Eject the CD: the data will be stored in the new format.
- Now you can repeat for another disc.

Annoying indeed and sorry for inconvenience. Unless you are extremely
short in HD space, you can keep the old DB as long as needed.


Extended Workman DB features.
=============================

Disc information (workmandb)
----------------------------
Disc is considered as single artist, if the artist name is present
and non-empty: otherwise a multiple artist disc is assumed.

If track name starts with '+', the continuation will be accepted as
track artist (multi-artist disc) or track extra (single-artist disc)
information. Double slash (//) in the first line will have the same
effect as the following part starts at a separate line preceded
with '+'.

Any information from third and following lines related to same track is
always appended to details while space allows, without "//" processing.


Preferences (workmanrc)
-----------------------
Sadp will first get the play list according to old sadp style.

Then it will try to access workman  DB  preference file  as specified by
WORKMANRC  environment string,  or  as  ~/.workmanrc, if the environment
string is absent. In case the file is  found and contains play list(-s)
for the disc, the preference set will be created for each play list with
the original play list name and list of tracks. Each 'dontplay' line adds
a track to skiplist in the last created preference set, if any.


INFORMATION NOT SUPPORTED BY OLD SADP AND NOT MENTIONED ABOVE IS IGNORED!


