----------------------------------------------------------------------
bookmarker
A WWW based bookmark management, retrieval, and search tool.
Copyright (C) 1998  Padraic Renaghan

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 of the License, 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.


Padraic Renaghan
e-mail <padraic@renaghan.com>
bookmarker home <http://www.renaghan.com/bookmarker/>
personal home <http://www.renaghan.com/pcr.htm>
snail mail:
 1244 N Wood St #3
 Chicago, IL 60622
----------------------------------------------------------------------
These instructions refer to my configuration of bookmarker (PHP
3.0.7, PHP Base Library 7, MySQL 3.22.21, Apache 1.3.6, Red Hat
Linux 5.2). bookmarker has only been tested under this configuration,
though it  should work in any PHP environment with a PHPLIB supported
database.  Currently, PHPLIB supports MySQL, PostgreSQL, Oracle,
Sybase and  ODBC databases. bookmarker supports PHPLIB 7.

These instructions assume that you have the following working
together: Web Server, PHP, PHPLIB, and database. I recommend the
following configuration:

- Apache Web Server (http://www.apache.org/). I recommend downloading
the source and compiling it yourself so that you can compile PHP as
an Apache module. NOTE: The RPM or other binary version should work
as well.

- PHP (http://www.php.net/). Again I recommend downloading the source
and compiling it yourself so that you can compile PHP as an Apache
module. NOTE: bookmarker should also work using PHP as a CGI
executable either compiled yourself or from a binary distribution of
PHP.

- MySQL (http://www.mysql.net/). You can either compile the source,
or in my case I downloaded the binary RPMs from the MySQL website.
Either should work.

- PHPLIB (http://phplib.shonline.de/). Source only. Download and
install. Make sure you can get the example pages working before you
move on to installing bookmarker.

--
bookmarker installation
(after untar/unzip the distribution file to a temporary location...)

1. The stuff in the /bklib subdirectory needs to end up in your
PHP include path. You can do this by copying the files in /bklib
to an already existing directory in the PHP include path, or
move the /bklib directory to somewhere like /home/httpd/lib/bklib
and then put /home/httpd/lib/bklib in the PHP include path - this is
the better option (see php3.ini file)

2. Update the bklocal.inc file with the name of your bookmarker
database and the user ID and password used to connect to it. I use
"bookmarks" as the name of my bookmarker database. Review the
contents of this file and update to support the database you are
using.

3. Update the bookmarker.inc file with the configuration settings
for your environment. Make sure the template_dir variable points to
the final location of the templates subdirectory you setup in step 1.

4. Copy the files in the /web subdirectory to a directory served by
your web server (something like /home/httpd/html/bookmarker). 
You may customize the look and colors used by bookmarker in the bk.css
(Cascading Style Sheet) file. Full customization is available with the
FastTemplate support in bookmarker. Update the files in the /bklib/templates 
directory to create the look & feel and language that you desire for your
installation of bookmarker.

6. Copy files in the /images directory to wherever you keep graphic 
files used by your web applications (like /home/httpd/html/images). 
NOTE: you may need to update image_url_prefix in bookmarker.inc to
point to this directory.

7. Create the tables in the database used by PHPLIB and bookmarker
using the bookmarker.sql definition. In MySQL this can be done
(assuming you have created a database named bookmarks) with the
following command:
  mysql bookmarks <bookmarker.sql
As recommended in the PHPLIB installation, the PHPLIB auth tables
should reside in the same database as the bookmarker tables.

8. The bookmarker.sql script creates a sample user with sample
bookmarks to get you up and running quickly. The user ID of the
sample user is "bk" and the password is "bk". Additional users can be
added to bookmarker using the user page. If you add users outside of
the user page, make sure the password is stored with the
PASSWORD('yourpassword') function. Users with update rights need to
have "editor" in the perms column of auth_user. "editor" permission
allows a user to add/update/delete/select bookmarks, "guest" allows
select only, and "admin" allows same as "editor" plus being able to
add/update/delete/maintain bookmarker users.

9. If you want to support the guest functionality of bookmarker, make
sure to add a user with username of "guest" and password of "guest".
Read-only users like guest should have "guest" in the perms column of
auth_user. Update the guest_user_select_user variable in bookmarker.inc 
to define the username of the bookmarks that guest gets to display.

10 If you are running on a Windows platform, edit the
class.FastTemplate.inc file in the /bklib directory and change the
WIN32 variable in the class section at the top to "true"

11. To give bookmarker full control over character handling,
especially quotes, you must turn magic_quotes_gpc, magic_quotes_sybase 
and magic_quotes_runtime off. You can do this in the php3.ini file
or if supported by your webserver in the .htaccess file.n

12. Open the index.php3 page in your browser, click the "plain list"
link on the top of the start page, enter "bk" in the user ID field,
enter "bk" in the password field, click "Login" button, and enjoy!

Install FAQ
-----------

If you receive a message like:
  "Fatal error: DB_Sql is already a function or class in 
   db_mysql.inc on line 12"
when you run bookmarker, then you have included the DB_Sql class twice. This is most often caused by having the prepend PHP.INI option set to include a file as well as including the file in the page source itself. bookmarker includes all pages it needs in its source files. It does not support the PHP.INI prepend setting for any classes it uses (PHPLIB or otherwise). Remove the prepend setting from your PHP.INI file to aleviate this problem.

-- CONVERT Netscape Bookmarks --
I have made the script set I used to convert my Netscape bookmarks
file into a series of SQL INSERT statements which I then piped to
MySQL in order to initially populate the database. The scripts aren't
really a part of the distribution, but I figured some of you might find
them useful. See the files named ns_convert*. You should setup your user ID
in bookmarker before running this script so you can update the
ns_convert.awk file to load your bookmarks under your user ID.

-- UPGRADE Instructions --
Version 1.6 - Starting with this version, bookmarker works with
PHPLIB version 7 only. Please upgrade your PHPLIB installation
before upgrading to bookmarker version 1.6.

Version 1.5 adds a keyword field to the database and the ability to save
searches in the database. A new field on the bookmark table and a new
search table are needed. Run the alter-1.5.sql script against your
bookmarker database to update it.

Version 1.3 now encrypts user password using the built-in PHP md5 function
instead of using the MySQL password() function. Therefore ALL existing
user passwords must have their passwords updated to the md5 version.
Included in the dist is the update-1.3.sql file. This will allow you
to set the password for the admin user to "bk" so that you can login
to bookmarker and change the passwords for all users - just use the
user.php3 page and enter in the passwd for each user, this will 
automatically update it to the new md5 encrypted version.

Version 1.1 adds two new fields to the auth_user table. Please read and
apply the contents of the alter-1.1.sql file to bring your database
up to date. You will also want to populate these new fields in the 
auth_user table (name, email) so that the mail-this-link function works
properly.

If you are running a version of bookmarker older than version 0.8,
please read and apply the contents of the alter-0.8.sql file to
bring your database up to the version that 0.8 requires.


bookmarker installation end
--
