cdd USAGE MANUAL 
(some short notes for improved usage)
Antonio Maschio 2006, <tbin at libero dot it>

the cdd set is a collection of tools for compact discs database maintaining,
written in bash. The database is a text file where records are listed one 
per row. The programs are:
cdd             is the actual database info extractor
add2cdd         is a tool for adding coherent data to the database
custom.data     is a file in which some customizable information is written,
                and it's the only file that could safely be changed.

cdd, add2cdd and custom.data must be written always in lower letters.

The database file
-----------------

The database file is cd.db (by default, but you can customize it changing 
the relative name into the file 'custom.data'); it's a text file, editable
with any editor, in which each line is a record.

Each record is composed by five fields, separated by a special character (by
default it's the vertical bar, but again it's customizable into the file 
'custom.data'); these fields are:

Artist(s)     : the name of the singer/singers or of the group
Title         : the title of the record (if there's more than one CD, you can
                add notes into parenthesis like this: (3 CDs)
Year          : the year in which the record has been issued the first time
                (e.g. Revolver, by the Beatles, should report 1966)
Issue         : the year of the CD manufacture (e.g. revolver could report
                2004 if it has been printed in that year)
Notes         : some notes in free format

Any field but the first may be void. All data are in lower characters.

You can use the file cd.db or another by setting its name into 'custom.data', 
or you can use another file on-the-fly using the -f  option:

$ cdd -f other.file [pattern]

The special markers
-------------------

Usually, cd date may be the same of the cd first issue (which means the record 
is rather recent) or they differ if it's a reprint, maybe from an LP. 
CD manufacture date is so followed by a special marker:

> means no reprint date is found, but track listing is complete; e.g.: 1966>
] means a reprint date is found, and track listing is complete;  e.g.: 2004]

Bootlegs, live and original collections should report the > or ] marker.

If the issue and manufacture years differ and no special marker is present, 
the cd **does not** feature the same track listing of the original record 
(excluding any additional bonus track). 
The output is influenced by the ']' and '>' markers; if cdd suspects that
the record hasn't got an original tracking list, or that you've typed a wrong 
year, an asterisk (*) is printed after the issue year. 

Other conventions:

v.v. means 'various years' (the record is typically a collection)
^^^^ means 'unknown data' (unavailable).

Output Formats
--------------

cdd simply investigates into the database file and prints all the lines 
responding to the search criterion according to three types of format:

- Plain: it's a format that reports all the unordered information
  available; it simply changes the separator with a tab char (-N option).

- Aligned: it's a columnized format, in fixed fields adapted for a terminal
  80 characters wide (-A option)

--Framed: it's a format in which all the information is reported into a
  mask; it's useful for writing stickers (-F option).

Usage
-----

$ cdd [OPTIONS] [pattern]
Options:
  -a            print all voices in the database
  -A            align output in fixed-size colunms (may trim fields)
  -c            report total number of records in the database and exit
  -C            add number of records found to search report 
  -f <file>     extract info from <file> rather than from cd.db 
  -F            frame output (may end in a long listing)
  -h --help     print this help and exit
  -n            print record number for each output line (unformatted outputs)
  -N            print output in plain format (may give uneasy listing)
  -o a|r|y|i|n  output only selected field (unifying multiple identical lines)
  -r            reverse sorting
  -s a|r|y|i|n  sort records only according to selected field
  -v --version  print version and exit
  -x a|r|y|i|n  limit search only to selected field
  -y            print a note about issue years rules and exit
Notes:
1. -s, -x, -o options must be followed by a selector char for field:
     a   artist name,
     r   record title,
     y   year of original record issue,
     i   CD manufacture year, if found (type cdd -y for info),
     n   notes about the recordings (if any);
2. -o selected output has precedence over -A aligned or -F framed modes;
3. if set together, the last among -A, -F and -N determines the output format.
4. if no pattern is given, all the records will be shown.
5. option -a is not necessary, since cdd alone performs the same operation.
   it's been inserted for coherence with most of bash scripts.

The pattern may be any combination of characters including the space: to look
for 'pink floyd' just type 'pink fl'; if you type 'pink' you could find also
'pink fairies', 'frijid pink' or else.
The pattern is checked against any field; so the previous search could match
even titles containing the word 'pink' ('in the land of gray and pink', by 
Caravan, for instance); if you want to limit the search to a specific field,
e.g. authors, use the option -x:

$ cdd -xa pink 

add2cdd behaves like a wizard program. Simply follow its instructions: you
will be asked to add data for each field of the record. 
When you want to stop, simply insert a void Author (simply typing <Return> 
when asked). That's all. It will take care of saving info in the correct format
into the database, with the right separator, and then sorting the whole file.
As a bonus, it will add some log information about the date in which a record
has been added into the file .cdd.log (the name of the log file is customizable
into the system file 'custom.data').

custom.data contains some user customizable data:

* the database filename (by default "$HOME/bin/cd.db")
* the field separator (by default "|"; it must match the database separator
* the filenames for tempfile (by default "/tmp/tempfile") and deadsearch (by
  default ("~/dead_search")
* the log file name (by default "$HOME/.cdd.log")
* the main view (by default ALIGNED, among PLAIN, ALIGNED, FORMATTED)

Tips
----

1. if you want to know how many records begin the letter w:
$ cdd -xr -or ^w

2. if you want to know how many artists end with the letter y:
$ cdd -xa -oa y$

3. if you want to know all the records you have, that have been issued the first
time in 1970, ordered by issue date:
$ cdd -xy -A -si 1970

4. if you want to know how many records you have:
$ cdd -c

5. if you want to know how many records by Pink Floyd you have:
$ cdd -C pink floyd

6. if you want to check what records have not a correct issue year set or
a not original tracking list:
$ cdd -A -xi | grep \*

7. if you want to check what records have incomplete fields (containing ^^^^),
reporting even their counting:
$ cdd -C "\^\^\^\^"
