
			      Addressbook 0.5
			============================
			      by Clemens Durka
		      (durka@informatik.tu-muenchen.de)

				  MANUAL

Addressbook is a programm to manage your addresses, phone numbers,
e-mailaddresses and everything which is now written in your rolodex.
Addressbook is copyrighted by Clemens Durka, but available under the GNU GPL.

This manual is in developpement, to get an up to date version, please consult:

http://wwwmayr.informatik.tu-muenchen.de/~durka/addressbook/manual.html


1. INVOKING ADDRESSBOOK

To invoke addressbook, simply type addressbook. Then it will read the global
configfile (normally /usr/local/lib/addressbook/addressbook.config) and, if
you have, you private configfile (normally ~/.addressbook.config) to override
some defaults.

There are the following commandlineoptions:

-a  or -addrfile         path and filename of the addressfile to load
-c  or -configfile       path and filename of the configfile to load
-l  or -language         language (currently english, german, french)
-ld or -libdir           path or the library directory
-hlp                     show some help

There are the following environementvariables:

ADDRBOOK_LIBDIR          libdir         (same as -ld)
ADDRBOOK_ADDRFILE        addressfile    (same as -a)
ADDRBOOK_CONFIG          configfile     (same as -c)


2. THE FIRST STEPS

Once invoced, you should get a nice window with a menubar on the top,
some entryfields left, a listbox with all the names in it right, and
some buttons on the right and the bottom.

Display address:
Whenever you press the mousebutton on a name in the listbox, you get
the detailed address in the entryfield.

Moving in database:
By pressing the buttons with the triangles you can move in the
listbox. By pressing on of the buttons (A-Z) you jump directly to the
corresponding letter. By typing some letters in the field beside the 
goto button, you jump to the name beginning with these letters.

Searching:
Press the leftmost button (Clear / New) to clear the entry field. Then
fill in the fields, you want to search for. Then press the 'Search'
button. The corresponding names will appear in the listbox. If you
press the rightmost button (General View) you see all names again.
Example (with the exampledatabase): Press 'Clear', put the letter 'D'
in the country field, press 'Search'. Now you will see all Germans.

Delete a record:
The button 'Delete Record' removes the record actually displayed.
Attention: For the moment, there is no 'Undo' so deleted records will
be lost after the next saving.

Add a record:
Press 'Clear' to clear the entryfield. Complete the fields in the left
part. Press 'Add record' to add the record. Confirm it.
For the contents and the form, you should type in the data, please see
the dataformat section in this manual.
If you add several records wish are similar in some fields, you can 
omit pressing 'Clear' and just change the fields, which are different 
before pressing 'Add record'. Attention: The record is only added in
the database in the working application. You have to save changes to
disk, before leaving the programm.

Change an existing record:
Select the record you want to change, so that it is in the left
fields. Edit the fields you want to change. Press 'Change Record' and
confirm. Changes get written to the file on the next saving.

Saving changes to disk:
Invoke File -> Save, if you want to save it with the same name, 
File -> Save as, if you want to change the name. If you call Save as,
the dataformatfile gets copied automatically.

Loading an other database:
Invoke File -> Load and select the other database

To exit the programm:
Invoke File -> Exit or press Ctrl+Q. Dont forget to save before
leaving, if you made some changes.


3. THE MENUBAR

The File Menu:
Load, Save, Save as, Close and Exit does what it should do :-)

Print invokes printing, see unter printing
Import and Export is not implemented yet, sorry.

The Edit Menu:
The same, than you can do with the buttons.

The Goto Menu:
The same, than you can do with the buttons.

The Option Menu:
Change several options.

Searchoptions:
exact search:      the fields searched for must match exactly.
wildcard search:   search with wildcards like in the shell ('*','?','[]')
                   (like: '*Main Street' 'Hauptstr.*' '[A-C]*')
regexp search:     Searches for regular Expressions

Result to stdout:  Switches the action for the buttons down right. Eigher
                   they invoke a program or they write the corresponding
                   data to stdout.

Special caracters: Defines what happens with non-ASCII caracters. Either
                   leave them and use ISO (recommended) or convert to TeX

Change Preferences: Sorry, but this doesn't work quite well now, changes dont 
                   get saved. Please modify the configfile (see CONFIGFILE)

Countries:
Here you can see all countrycodes as you should use them.

Help:
Some help


4. THE PHONE, FAX, MAIL AND EMAIL BUTTONS

These buttons situated on the bottom right do eigher put the contents
of the corresponding field to stdout or they give them as argument to
a program. Change the behavior with Options -> Result to stdout.
The programms called are defined in the configfile, normally you can
put put there a programm to dial, to compose a fax and send it, to
write a email and send it or to write an enveloppe with the printer.
If you have a good program, which fit in there, please write to the
author.


5. CREATE A NEW DATABASE

Each database has a datafile and a formatfile. Normally the datafile 
ends with '.dat' and the formatfile with '.dat.fmt'. You have to create
a dataformatfile and an empty datafile to begin a new database. So
the easiest way to begin with a new database is to copy one of the
sample dataformatfiles there where you want to have your addressfile.

Ex.: You want to create a personal database in ~/addressbook which
will have the name addresses.dat
Create the directory:
  mkdir ~/addressbook
Copy the sampledatafile to as addresses.dat.fmt to it:
  cp /usr/local/lib/addressbook/sample/addresses_private.dat.fmt \
    ~/addressbook/addresses.dat.fmt
Modify the datafile to your needs (read the section DATAFORMATFILE)
  vi ~/addressbook/addresses.dat.fmt
Create an empty datafile:
  touch ~/addressbook/adresses.dat
Then invoke 'addressbook -a ~/addressbook/addresses.dat and you have
your new empty database. Don't forget to save before quitting.


6. DATAFORMAT

The Format, data is stored is quite simple: 

one file (usually with extension .dat) holds all the data, one line
per entry, fields separated by a special character (usually ';')

a second file (extension .dat.fmt) holds the format definitions, that
means, which field contains which data, which fields get shown in the
listbox and which which format

The programm fully supports 8 bit iso-latin fonts, so enter any special
caracter just like this. (german umlauts, french accents). If these
special caracters are on your keyboard, but dont work, you maybe need 
to modify Xmodmap.

Format for some fields:

addon		something like c/o which doesn't belong to street

street		just as usual in the country: first streetname and number or
		first number, then streetname (like in France)

country		Please use country abbrevations as on international number
		plates. By clicking on the Button Countries you get a list.
		Full names will be expandes automatically.
		ATTENTION: You have to enter a country, if you want to
		have the full functionality of the phonebuttons.

zip		Zip Code, including state (for USA) or letters (for NL)

city		Cityname without zipcode

birthday	feel free, but consequent. I use dd.mm.yyyy   
		maybe sometime a 'birthday reminder app' will be added

phone*		IMPORTANT: put it, as if you were already in the country
		international dial prefixes are added automatically, if
		your configuration in addressbook.config is correct.
		p.ex.:
		1-234-567-7890 (USA & Canada)
		(089)1234567   (Germany and many others)
		12345678       (Danmark and France exept Paris)
		(1)44556677    (France around Paris)

email		full emailaddress


7. CONFIGFILE

You can change much of the behavior of the program in the configfile.
Most of the options have resonable defaults, so you don't need them.
All of these can be overwritten with a personal configfile.
You can look in libdir/addressbook.config.sample for some ideas.

The following options should be set by the installation,
but you can change them:

libdir		path to the librarydirectory (the only really important thing)
adrfile		the default addressfile
language	the default language (english, german, french)
mycountry	the countrycode of your country (p.ex. USA or CDN or D)
myareacode	your telephone area code (for correct omission for local calls)
                including the 1 for USA (like 1212 for New York,
		089 for Mnchen, 1 for Paris)

These options you have to change manually, if you need:

dialoutlocal    Your dialoutprefix for local calls inside your telephone
		installation. If you have a standalone phone, it sould be empty
dialoutdistance	Your dialoutprefix for long distance calls inside your
		tel. installation
callprog,phone  Programm which is called to dial a phone number
		(use %number for number)
callprog,fax	Programm which is called to send a fax (use %number)
callprog,email	Programm which is called to send a email
		(use %number for emailaddress) 
only_stdout     Actionbuttons only put to stdout (instead of calling
		upper programs)
searchtype	The default searchtype (exact, match, regexp) 
select_mask	The selection mask for filenames (endings of datafiles)
texconvert	Conversion to TeX


Printingrelated options (some thing might not work, as printing is in
developement). In parentheses possible settings, default is the first one.

printform	Default form and fields to print (address, name,
		nametel, addresstel, almostever, everything)
printopt	Default print output (latex, text, ascii, ps)
printtype	Print as (line, box)
printarea	Area to print (all, selection, region)
printfile	File in which to print (use '| lpr' to send to printer)
print,name	The fields to print when printform is name.
print,nametel   same (as well for address, addresstel, almostever, everything
		Entries which belog together are in curly braces {}
zipformat,eu	Format for the order of zip and city (Europe =  zip city)
zipformat,uk	Format for the order of zip and city (UK     =  city zip)
zipformat,us	Format for the order of zip and city (USA    =  city , zip)


These options normally should not needed to be changed, they have hardcoded
defaults, so you neednot mention them in your configfile:


entrywidth	width of the entryfields
listboxwidth	width of the listbox
listboxheight 	height of the listbox
makebackup	make a backupcopy


8. DATAFORMATFILE

The dataformatfile defines the semantic of the datafile. Each field of
the database has to be identified by a contents type. There are many
predefined types, but you can define yourself some new ones.
This is needed, so that the program can identify special fields, like
the country or the phonenumber and for selection to print.

In the dataformatfile, you have to write in each line the number of
the field (beginning with 0) and the type.

For example:

0 firstname
1 lastname
2 phonepriv
3 phonework
4 other1

If you define your own type (other1 - other9) you have to supply a
label (label1 - label9 for it)

label1 "Special purpose field"

Some other things in the dataformatfile:
separatorchar	(you should use ';' unless you have important reasons)
listboxformat	("%s %s" or "%s, %s", depending if you want a comma between
		the fields. (like Firstname Lastname or Lastname, Firstname)
listboxentry1	The 1st field in the listbox (sorting criteria)
listboxentry2	The 2nd field in the listbox

Following types for fields are possibe:

Field-ID              german transl.          french transl.

mrmrs                 Anrede                  M/Mme/Mlle
title                 Titel                   Titre
firstname             Vorname                 Prenom
lastname              Nachname                Nom
company               Firma                   Entreprise
institute             Einrichtung             Institut
departement           Abteilung               Departement
addon                 Zusatz                  Supplement
pobox                 Postfach                B.P.
street                Strasse                 Rue
country               Land                    Pays
zip                   PLZ                     Code postal
city                  Ort                     Ville
state                 Staat                   Etat
province              Provinz                 Departement
county                Bezirk                  Arrondissement
birthday              Geburtstag              Date de naissance
phone                 Telefon                 Telephone
phonepriv             Telefon privat          Telephone prive
phonework             Telefon Arbeit          Telephone au travail
fax                   Fax                     Telefax
email                 E-Mail                  E-Mail
category              Kategorie               Categorie
remark                Bemerkung               Remarque
other1                zu definieren           a definer
other2                zu definieren           a definer
other3                zu definieren           a definer
other4                zu definieren           a definer
other5                zu definieren           a definer
other6                zu definieren           a definer
other7                zu definieren           a definer
other8                zu definieren           a definer
other9                zu definieren           a definer


If you define your own fields and you want to print them, you have
to modify print,address and similar in the optionfile.


9. THE LITTLE PROGRAMMS TEL, FAX AND EMAIL

Just call these programms with the name, you want to look for as argument,
like 'tel Pumuckl'. If it doesn't work, maybe you have to adjust the
variables $CONFIGFILE inside the programm.


10. PRINTING

Printing is under developement, so it works only partially. If you want
to send the files directly to the printer, you have to set the printfilename
so something like '| lpr'. If you want to modify the texfiles before printing,
you have to uncomment the line, where they get deleted (around line 1844).


11. ANYTHING ELSE?

Thats all, I have written now, but any questions, comments,
suggestions, complaints, assistance or volunters for translation in other
languages are very welcome. Contact me please:

email:	durka@informatik.tu-muenchen.de
WWW:	http://wwwmayr.informatik.tu-muenchen.de/~durka
irc:	Clemens (sometimes at least)

Clemens Durka

