ZBKB					USER GUIDE
====					==========

Version 0.1 

 *************************************************** 
 * IMPORTANT - ENSURE YOU HAVE READ THE README     *
 * FILE AND INSTALLED ZBKB AS PER THE INSTRUCTIONS *
 * CONTAINED THEREIN!                              *
 ***************************************************


Introduction
------------

This document will eventually form the main User and
Administrator documentation for ZBKB (ZazzyBob
Knowledge Base). In it's present form, it's a quick
series of step-by-step instructions on how to achieve
certain things and get the Knowledge Base up and running
quickly. This will change in later versions, and this 
documentation will eventually be distributed in various
formats, but for now, it should be enough to get you going!

It'll probably appear a little terse - I'm writing it from
a programmers' viewpoint. I will fix this later on - but I
have worked hard on the coding for this project for many
months, and just want to get it "out there" for the community
to play with! If any documentation writers want to contribute
to the project, drop me a line at kevin@zazzybob.com.

I'd recommend that you have this document open in a terminal
(or hard copy) and read through it whilst experimenting with
ZBKB. If you make a mess of things, you can always logout, run
the setup_db script again (included in the tarball), and return
the database to its initial state.


What's Included with ZBKB
-------------------------

After installation, you'll end up with a variety of files in 
whatever directory you specified in the _WWW_ROOT variable.
These include many PHP files (which make up the program), a
single CSS file which provides the style definition for the
interface, a text file called motd.txt and a file access_log.

Of worthy note here are the following:

Whatever you place in motd.txt will be displayed to any user
after they log in to ZBKB - yes, it's /etc/motd for ZBKB!

The file access_log contains all attempted login details, whether
the login was successful (SUCCESS), a bad username was supplied
(BADUSER) or a bad password was entered (BADPASS). A date and time
is also given, as is the username supplied (if any) and the
originating IP address of the login attempt.

Study the access_log file regularly to monitor the system for abuse
and intrusion attempts.


Database Structure
------------------

If you're interested in how the database is put together, study the
init_db.sql script included in the distribution tarball. 

From a "user's" perspective, there are three things to worry about.
Article categories, article sub-categories, and the articles themselves.
This allows us to have articles about shell scripting in the "bash"
subcategory of the "shells" category. Or articles about hard disk 
parameter tuning in the "disks" subcategory of the "hardware" 
category. Only admistrative users can add or remove categories or
subcategories. Standard users can be given rights to add and/or remove
articles from the knowledge base.

Two test categories (each with three test subcategories) are included
with the database, so you can start adding and removing articles and
testing ZBKB straight away. These can be deleted once you want to
start adding your own categories and subcategories to the database.

The database is designed to be pretty intuitive, and it has various
advanced error checking routines, and shouldn't fall over at any point.
Obviously, the rigours of testing may disprove this ;-) I've found
that as long as you can install ZBKB successfully, it will work
reliably.


Your first login
----------------

First things first. Ensure that you are using a Javascript enabled 
browser, that accepts cookies. Without either of these two items,
ZBKB will not work! I have tested ZBKB using Mozilla Firebird
(0.9 and 1.0PR), and (boohiss) Internet Explorer 6 SP1.

To get going, fire up your browser (and assuming that your PHP files
are installed in wherever Apache's DocumentRoot is pointing), browse
to http://localhost

You will then be presented with the login dialog.

Initially, ZBKB comes pre-installed with one user account, "root".
This is the administrative user for the database, and cannot be
deleted. 

The initial "out-of-the-box" login credentials are as follows:
  
 			username:		root
			password:		password

Both username and password are case-sensitive. Passwords are stored
internally within the database in an encrypted format for security.

Obviously, once you login, you should change the root password.

Anyway, enter the username and password, click "Login", and you should
receive the authentication page. For administrative users, you will see
two links here "Continue" and "Administration". Standard users will just
see the "Continue" link.

Continue takes you to the main Database, whereas Administration takes
you to the Administrative section of the Database.

Also on this authentication page, you can see the output of the
motd.txt file, if it exists. This is a good place to warn users of 
problems with the Database (it'd also be nice if you warned me too!).


Navigating the Database
-----------------------

After logging in and authenticating as root, we can navigate through
to the Administrative section of the database. You'll be presented
with two sections of links. 

The top section of links is standard for both users and administrators
(with one exception, more on this later). This is the section of links
that you would see if you clicked on the "Continue" link on the
authentication page.

The links within this top section are:
  
  Add Article	  - Add an article to the knowledge base
  Search Articles - Search for, and optionally delete, articles 
  Admin Menu      - Administrators only - brings up the Admin
				    Control Panel
  Control Panel   - Change your own password
  Logout          - Logout of the database

The bottom section contains links that only Administrative users will
have access to. You can bring this up at any time by clicking the
"Admin Menu" link. This section is known as the "Admin Control Panel".

The links contained within the "Admin Control Panel" are as follows:

  List Users	  - List all current users configured on the system
  Add User		  - Add a user to the system
  Remove User	  - Remove a user from the system
  Change Users Password - Forcefully change another users password
  List Categories - List all articles categories currently set up
  Add Category    - Add a category to the database
  Remove Category - Remove a category from the database
  List Sub Categories    - List all subcategories
  Add Sub Category       - Add a sub category to the database
  Remove Sub Category    - Remove a sub category from the database

Most of these items should be fairly self explanatory.

After you've logged in as root for the first time, head over to
the "Control Panel" in the top section. Then click the 
"Change Password" link which will appear in the bottom section to
change the root password. This is highly important!


Users and Permissions
---------------------

At present, three permissions are implemented. These are "write",
"delete" and "admin". 

Write permission allows a user to create new articles in the database.
Delete permission allows a user to remove articles from the database.
Admin permission implies the above two permissions, and also allows the
addition/deletion of users, categories and subcategories.

You should set most standard users up with just "write" permission.

If you give a user no permissions at all, they will still be able to
login and search through articles on a "read-only" basis.


Using the Database
------------------

As root, set up some users with the required permissions. Using the 
links provided within the Admin control panel, you can add and remove
categories and sub-categories. Various constraints are in place to stop
you removing categories and sub-categories upon which articles, etc,
depend. You will receive an error message if you try to remove such
categories.

All forms have a common theme. Fill in the data, press the button at
the bottom of the form, then the action will be performed. A 
confirmation (or error) screen will then appear letting you know how
things went.

The "removal" forms display a list of all current users/categories/etc
and allow you to click a radio-button to the left of the user/category
that you want to delete. Click the "Delete" button at the bottom of
the form, and the record will be deleted (if nothing depends on it).


Searching and Deleting Articles
-------------------------------

A form worth special note is the "Search Articles" form. This form
allows you to search all articles (in a specified field), using AND
or OR logic. Type in your searchterms, select the logic required,
select the field you want to search, and click the "Search" button.

Leave the searchterms box blank to list all articles (i.e. match
everything - because everything contains at least "nothing"!)

You will then receive a list of matching articles. Click the radio
button to the left of the required article, and then click the
"Show Details" button. The full contents of that article will be
displayed. If you have Admin OR Delete permissions, you will see a
"Delete Article" button at the bottom of the "Show Article Details" form
that allows you to remove the article from the database. This action
cannot be undone.


Conclusion
----------

I know this was very brief and terse, but it should give you the 
grounding to start experimenting with the database. I will produce
proper documentation when time permits, but if somebody wants to help
with this, please e-mail me at kevin@zazzybob.com. 


Bugs/Omissions 
--------------

At the moment you can only add/remove things - no mechanisms are in
place to edit and amend articles/categories/subcategories/users.
This functionality will be added in a later release.


That's it for now!
Cheers,
Kevin Waldron

kevin@zazzybob.com
http://www.zazzybob.com