  pi-address FAQ
  Michael Wiedmann, mw@miwie.in-berlin.de
  v1.5, May 21, 1998

  This document is the FAQ (Frequently Asked Questions) for pi-address,
  a GUI frontend for the address database of a 3Com Palm Pilot.
  ______________________________________________________________________

  Table of Contents:

  1.      General

  1.1.    What is pi-address?

  1.2.    Can it be used standalone?

  1.3.    Can it read direct from my Palm Pilot?

  1.4.    Can it write direct to my Palm Pilot?

  1.5.    Can it sync my database?

  2.      Installation

  2.1.    Where to find?

  2.2.    Are there precompiled binaries?

  2.3.    Precompiled packages

  2.3.1.  Is there a Debian package?

  2.3.2.  Is there a RPM package?

  2.4.    How to build?

  2.5.    Why are absolute pathnames for the libraries used?

  2.6.    Where to install?

  2.7.    Where to put the online FAQ files?

  2.8.    Where to put the configuration files?

  3.      Using the program

  3.1.    Can I specify a default database to load on startup?

  3.2.    Where does pi-address look for the database files?

  3.3.    Can I display the contents of a "Note" in the main window?

  3.4.    How to import existing data?

  3.5.    How can I specify the device used for the Pilot?

  3.6.    Can I change the configuration file at runtime?

  3.7.    Can I change the fonts used in the various windows?

  3.8.    Printing

  3.8.1.  Can I print my records?

  3.8.2.  How is the encoding for the field names for printing?

  3.8.3.  Restrictions and known bugs on printing

  3.8.4.  Can I print to a file?

  3.9.    Why are there sometimes mixed languages in the menus/dialogs?

  4.      Known bugs

  4.1.    Exporting records as CSV file with large notes attached

  5.      Miscellaneous

  5.1.    Is this FAQ accessible via WWW?

  5.2.    Is there a mailing list?

  5.3.    Is there an announcement mailing list?

  5.4.    How can I contact the author of pi-address?

  5.5.    Which platforms are supported?

  5.6.    How can I contribute to this FAQ?

  6.      Credits

  7.      Copyright

  7.1.    How is pi-address copyrighted?

  8.      Links
  ______________________________________________________________________

  1.  General

  1.1.  What is pi-address?

  A GUI frontend to address databases from a 3Com Palm Pilot. It can
  read/edit/save address database files in PDB-format. Those files can
  be read from or written to the pilot using pilot-xfer from the pilot-
  link package. Starting with V0.2.0 it can read your address data
  directly from the Pilot.

  1.2.  Can it be used standalone?

  The program can also be used as a general address manager without a
  3Com Palm Pilot. Some of the record fields may not be very meaningful
  in this case.

  1.3.  Can it read direct from my Palm Pilot?

  Starting with V0.2.0 the program can read the address data directly
  from the Palm Pilot. Put your Pilot in the cradle, connect the cable
  properly and select Pilot / Read from Pilot from the menu or by
  pressing the button in toolbar.

  You will be prompted for pressing the Hotsync Key and the data is read
  into the pilot. Afterwards you can save the data to a file in PDB-
  format, the format used by pilot-xfer from the pilot-link package.
  An alternative way to get your address data is using pilot-xfer from
  the pilot-link-package.

  To fetch the database from your Pilot use the following command:

       pilot-xfer -f AddressDB

  1.4.  Can it write direct to my Palm Pilot?

  Starting with V0.2.1 the program can write the address data directly
  to the Palm Pilot. Put your Pilot in the cradle, connect the cable
  properly and select Pilot / Write to Pilot from the menu or by
  pressing the button in toolbar.

  You will be prompted for pressing the Hotsync Key and the data is
  written into the pilot.

  An alternative way to write your address data back to the Pilot is
  using pilot-xfer from the pilot-link-package.

       pilot-xfer -d AddressDB
       pilot-xfer -i AddressDB.pdb

  Before writing your database back to the Pilot you have to delete the
  database on the Pilot first and then install the saved data file using
  the second command (otherwise you will get duplicate records).

  1.5.  Can it sync my database?

  No, not yet. This maybe will be added in a future version. If you want
  to sync all your database files from your Palm Pilot watch out for
  Kpilot.

  2.  Installation

  2.1.  Where to find?

  You can always find the newest version of the software at
  ftp://linux.in-berlin.de/pub/pilot/pi-address.tar.gz.  This is a
  symbolic link to the actual archive pi-address-0.x.y.tar.gz

  There is a mirror site at ftp://walther.in-berlin.de/pub/pilot/. In
  case you have trouble to connect to the primary ftp server, try this
  one instead.

  For people in the US maybe this mirror will be much faster:
  ftp://pv915.pv.reshsg.uci.edu/pub/pilot/.
  Both above mentioned mirror sites usually are updated within hours
  after announcing a new release.

  If you are willing to setup another mirror site for pi-address please
  contact the author.

  2.2.  Are there precompiled binaries?

  You can find precompiled binaries (linked dynamically against
  libqt.so) at ftp://linux.in-berlin.de/pilot/binaries/ for the
  following platforms:

  o  Linux (ELF), i386

  o  Solaris, 2.5, Sparc

  If you find any problems using one of these binaries, please email the
  author with a detailed description of the problems.

  Alan Harder, the maintainer of PilotManager, is providing a
  precompiled binary for Solaris on his webpage
  http://www.moshpit.org/pilotmgr/binaries/misc/ (statically linked
  against pilot-link.a and libqt.a).

  2.3.  Precompiled packages

  2.3.1.  Is there a Debian package?

  No, not yet. If you are willing to maintain a Debian package please
  contact the author. Any help will be appreciated.

  2.3.2.  Is there a RPM package?

  Yes, Jon Lasser is maintaining a RPM package. There is a subdirectory
  ftp://linux.in-berlin.de/pub/pilot/rpm/ on the primary ftp site. You
  can find the RPM package on RedHats ftp site too.

  2.4.  How to build?

  Follow the instructions in the README file. Make sure that the include
  files and libraries for libqt.so and libpisock.a can be found.

  Both pilot-link.0.8.9, pilot-link.0.8.11 and pilot-link.0.8.13 have
  been tested and are known to work.

  gcc 2.7.2 and 2.8.1 have been tested on Linux and Solaris.

  The authors plan is to use GNU autoconf for configuring the package.
  This would be the best solution for solving problems in finding header
  files and libraries. The only problem is the lack of spare time...

  2.5.  Why are absolute pathnames for the libraries used?

  This was the only way, the author could figure out how to link one of
  the libraries dynamically (Qt) and the other statically (libpisock.a).
  If anybody knows of another solution for this, please email the
  author.

  2.6.  Where to install?

  In general pi-address does not rely on a specific directory.

  Just copy the binary to any directory which is appropriate for your
  system. There is a install target in the Makefile, check the variable
  $prefix in the Makefile, change if necessary and run make install.
  Depending on the directory where you want to install you may need root
  privileges.

  2.7.  Where to put the online FAQ files?

  The FAQ files can be accessed online by chosing Help / FAQ from the
  menubar.

  There is an install-doc target in the Makefile, check the variable
  $doc_prefix in the Makefile, change if necessary and run make install-
  doc. This target is also run if a make install is done. Dont forget to
  specify this new path in your ``configuration'' file for your
  HelpApplication. Depending on the directory where you want to install
  you may need root privileges.

  Specifying an empty entry for HelpApplication disables the menu Help /
  FAQ.

  2.8.  Where to put the configuration files?

  Starting with V0.1.2 there is a configuration file for the program. On
  startup the program searches and reads the configuration file in the
  following places (and in that order):

  o  /etc/pi-address.conf

  o  ~/.pi-addressrc

  The package provides an example configuration file with the program's
  default values. It's documented so the meanings of the key/value pairs
  should be obvious.

  3.  Using the program

  3.1.  Can I specify a default database to load on startup?

  Just give the pathname of the database file to load on startup on the
  command line, e.g. pi-address /path/to/AddressDB.pdb. (Thanks to Jon
  Lasser for suggesting this.)
  Create an alias like alias pi-address="pi-address
  /path/to/AddressDB.pdb" if you want to load the program the default
  database any time you start the program.

  Another possibility is to specify the default database in the
  ``configuration'' file with an entry like:

       DefaultDB = /path/to/AddressDB.pdb

  3.2.  Where does pi-address look for the database files?

  If you try to open a database file using File / Open pi-address will
  start searching in the following directories (in the shown order):

  o  $PILOT

  o  $HOME

  Of course you can change directories at your will in the file
  selection box.

  3.3.  Can I display the contents of a "Note" in the main window?

  As of V0.1.5 the contents of a Note can be displayed in the main
  window by specifying ShowNote = Yes in your ``configuration'' file
  (defaults to No).

  3.4.  How to import existing data?

  Importing records is done by selecting File / Import as CSV. Select a
  file in the file selection dialog. The records in this file will be
  merged into the currently opened database, if any.

  The format of a CSV-file is the same like the one of pilot-addresses
  from the pilot-link package. To see an example create a new database
  (File / New), add a new record and specify a unique entry for every
  field. Export this database as a CSV-file (selecting File / Export as
  CSV) and look at the file with your favorite text editor.

  If you currently maintain your address records with another program,
  export the records from this program as a text file, write a small
  converter with your favorite scripting language which converts this
  text file to CSV format. Import the converted file into pi-address,
  that's it.

  3.5.  How can I specify the device used for the Pilot?

  The default device name for communication with the Palm Pilot is
  /dev/pilot. If you have a symbolic link to the actual device used, you
  are done.

  You can specify a different device name in the ``configuration'' file
  with an entry like:

       DeviceName = /dev/name

  3.6.  Can I change the configuration file at runtime?

  As of V0.2.1 there is a new entry in the menubar File / Reread
  configuration file. If selected, the user configuration file will be
  reread and evaluated, changing the corresponding values in the
  program.

  3.7.  Can I change the fonts used in the various windows?

  As of V0.2.2 the user can configure the fonts used in the various
  windows through variables in the configuration file. The following
  variables are recognized:

     ListFont
        Font used for listing of all records in left window (Default:
        fixed).

     RecordFont
        Font used for display of a single record in right window
        (Default: Helvetica).

     EditFont
        Font used for displaying fields in edit dialog (Default: fixed).

  The main purpose of this is to provide the user a possibility to
  display address databases with non ISO8859-1 character sets. There is
  still a lot of work to do for this, but its a beginning.

  3.8.  Printing

  3.8.1.  Can I print my records?

  Yes, as of V0.1.2 there is rudimentary support for printing address
  records.

  Just select the category for which you want to print the records and
  choose File / Print from the menu bar. This will print all records
  selected through the category using a default value for formatting
  each record.

  As of V0.1.3 there is also a toolbar button for printing the selected
  address records. Pressing this button activates the same function like
  choosing File / Print from the menubar.

  You can modify the way the records are printed in changing the
  following values in the program's configuration file (see Section
  ``Where to put the configuration files'' for more information on
  configuration files):

     PrintingFontName
        The font to use for printing (Default: Helvetica, valid font
        names: Helvetica, Times, Courier)

     PrintingPointSize
        The point size for printing (Default: 8)

     PrintingFormat
        Which fields to print (Default: %l %f %p1 %p2 %p3 %c1, see the
        following explanations for the encoding)

     PrintTo
        Where to print to (Default: Printer, valid entries: Printer,
        File)

     PrintFileName
        The default print filename if printing to a file (Default: pi-
        address.ps)

  3.8.2.  How is the encoding for the field names for printing?

  The key PrintingFormat in the ``configuration'' file defines which
  fields will be printed for each record. The encoding of the fields
  follows:

  o  %l Last name

  o  %f First name

  o  %i Title

  o  %o Company

  o  %p1 - 5 Phone fields no. 1 - 5

  o  %a Address

  o  %z ZIP code

  o  %t Town

  o  %s State

  o  %n Country

  o  %c1 - 4 Customer fields no. 1 - 4

  Beginning with V0.1.3 the user can specify an optional width for each
  column (e.g. %20l).

  When specified it is used to calculate the width of the column by
  multiplying the specified width (= no. of characters to print for this
  column) by the no. of pixels of the widest character for the font in
  use. So there is always enough room to print width characters though
  in most cases there can be printed one or two characters more as
  specified.

  If no width is specified a default value of 20 will be used.

  3.8.3.  Restrictions and known bugs on printing

  o  Characters > 0x7F (e.g. german Umlaut-characters) will not be
     printed (this is a Qt bug, which will be solved in the next release
     1.40 of Qt).

  o  No header line on each printed page.

  o  All fields are printed on a single line.

  Expect these restrictions to be solved in future versions.

  3.8.4.  Can I print to a file?

  If you want to print to a file instead directly to a printer, choose
  File / Print from the menu bar and make the corresponding entries. You
  only have to set the Combobox Print to: to file, a default filename
  pi-address.ps in the current directory will be used if none is given
  in the setup dialog.

  You can specify the default destination for printing in your
  ``configuration'' file. Set the following if you want your default to
  be printing to a file:

       PrintTo = File

  You can change the default printing filename from pi-address.ps by
  setting:

       PrintFileName = /path/to/file-name

  3.9.  Why are there sometimes mixed languages in the menus/dialogs?

  People using a german version of the Palm Pilot OS will see mixed
  german/english text entries in some menus/dialogs. This is because the
  label names for the record fields are stored in the database file. If
  you open such a database file, the corresponding field names (e.g.
  Category, Last name, etc.) will be updated and will be shown in the
  language the database was created with.

  4.  Known bugs

  4.1.  Exporting records as CSV file with large notes attached

  If you try to export records as a CSV file (Comma Seperated Value) and
  one or more records have an attached note which contains one or more
  very long lines (about 60 chars.), the program dumps core with a
  segmentation fault. No known workaround.

  5.  Miscellaneous

  5.1.  Is this FAQ accessible via WWW?

  There is a little homepage at http://linux.in-berlin.de/pia/ with
  links to the online version of this FAQ (HTML, ASCII and PS format)
  and some screenshots.

  This may change without notice. A version of this FAQ is part of the
  archive in the doc directory.

  5.2.  Is there a mailing list?

  Not yet, if you are willing to setup a mailing list for pi-address
  please contact the author.

  5.3.  Is there an announcement mailing list?

  This may change without notice:

  Currently the author is maintaining an announcement mailing list. This
  is a closed mailing list used only for announcing new versions of pi-
  address. If you want to be put on this list by the maintainer send
  mail to majordomo@miwie.in-berlin.de with subscribe pia-announce in
  the message body.

  If this mailing list causes to much hassle (bounced messages, etc.)
  for the maintainer it will be closed down.

  5.4.  How can I contact the author of pi-address?

  You can reach him via email at mw@miwie.in-berlin.de

  5.5.  Which platforms are supported?

  pi-address is known to work on the following platforms:

  o  Linux, 2.0.x, i386

  o  Solaris, 2.5.x/2.6, Sparc

  o  NetBSD, Amiga

  o  FreeBSD, 2.2.5R, i486

  o  email the author if you run the program successfully on another
     platform ...

  5.6.  How can I contribute to this FAQ?

  Send mail to the author of this FAQ with complete information about
  the question and a suggested answer which you want to be included in
  this FAQ.

  6.  Credits

  Thanks to Rainer Doemer, Philipp W. Grau, Jon Lasser, Frank Ronneburg,
  Till Siering, Johannes Walther, Carsten Wartmann and Peter Weyers for
  giving me bug reports, hints, suggestions, ...

  Thanks to Rainer Doemer, Frank Ronneburg and Johannes Walther for
  providing ftp space to distribute the software.

  Thanks to Jon Lasser for maintaining the RPM package of pi-address.

  Thanks to Alan Harder for building a Solaris version and making it
  publicly available.

  7.  Copyright

  7.1.  How is pi-address copyrighted?

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2, or (at your option)
  any later version.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

  8.  Links

     pi-address
        ftp://linux.in-berlin.de/pub/pilot/

     pi-address (Mirror)
        ftp://walther.in-berlin.de/pub/pilot/

     pi-address (US Mirror)
        ftp://pv915.pv.reshsg.uci.edu/pub/pilot/

     pi-address FAQ
        http://linux.in-berlin.de/pia/

     pilot-link
        ftp://ryeham.ee.ryerson.ca/pub/PalmOS/

     Qt http://www.troll.no/

