========================================
  DOCUMENTATION FOR RESEARCHGUIDE 0.5
========================================


E-mail researchguide-info@lists.sourceforge.net with any questions.



TABLE OF CONTENTS
--------------------------------------
I.   Introduction
II.  Installation
III. Using ResearchGuide
IV.  Call for developers





I. Introduction
--------------------------------------

ResearchGuide is a web application for creating, in a university library
setting,
  1. guides to resources and
  2. information pages about subject specialists.

It might also be useful in other settings such as a public library or a school.





II. Installation
--------------------------------------

PHP version 4 is recommended.
You will also need to have MySQL installed locally.
Set up a database called 'researchguide'.
Username: researchguide
Password: dbpass

Here's where you can get the database structure:
  1. Go to http://researchguide.sourceforge.net/guide/phpmyadmin/
  2. In the left column of the browser, click on 'researchguide'
  3. Click on the "Export" tab.
  4. The "Structure only" button should be selected.
  5. Click "Go".
  6. You should see some MySQL "create table" syntax and the like.  Grab
     this text and use it to set up your database.

phpmyadmin is bundled with the release.
You will need to customize it for your particular database (see instructions
for phpmyadmin).

For authorization: there's an admin directory inside the 'guide' directory.
If possible, set up your system to require authorization for anyone attempting
to access this directory.

To create site administrators, add their uniqname, or e-mail id (at U.
Michigan this was the part that goes before the '@' sign) to the admin
table in the database.

The auth system will need to set the HTTP variable $REMOTE_USER to the
uniqname or e-mail id of the person logging in.  ResearchGuide will look
for this variable and compare it against values in the admin table.

This was written around the particular auth system used at the University
of Michigan.  If your system doesn't work this way, it may be necessary
to design a different auth system.  A PHP-native system that could be
bundled with the ResearchGuide code would be ideal, it seems to me.  This
is an opportunity if you're at all interested in becoming a developer on
this project.

ENABLING THE AUTH SYSTEM
When you first install ResearchGuide, the auth system will not be
enabled.  To enable it, comment out the variable in the file:
'guide/lib/globals.php'

from this...
$REMOTE_USER = 'sampleadmin';

...to this.
// $REMOTE_USER = 'sampleadmin';





III. Using ResearchGuide
--------------------------------------

A. Basic features

Site administrators may create, edit or add both subject specialists and
research guides.  Individual specialists may only change their own
specialist pages or guides where they are the assigned maintainer.

FOR A NON-ADMINISTRATOR TO CREATE OR MAINTAIN A PAGE, SHE OR HE MUST
FIRST BE ENTERED INTO THE SYSTEM BY A SITE ADMINISTRATOR AS THE
MAINTAINER OF A PARTICULAR GUIDE.

LAST UPDATED
Guide and specialist pages both have a "last updated" message at the
bottom.  This is automatically updated when changes are made to the
database record.

INDEX TO GUIDES
You will see that on the index to all guides (guide/index.php), guides
are grouped into various broad areas such as General, Humanities and
Language and Literature.  This was designed around an existing
scheme at the University of Michigan.  You may wish to arrange this page
differently.

ACCESS TO ADMIN INTERFACE
Just go to the guide/admin directory on the Web.  As mentioned above
the setting when you download the software will be to have the
authorizations system disabled.

IMAGES
Pictures can be inserted into guides and specialist pages.  These should
be an appropriate size.  To display images, the image files must be
manually uploaded to the guide/images directory.  Then, when editing
information on a particular guide or specialist page, type the filename
into the "image" field.  For example, in the Philosophy guide you would
upload an image called socrates.jpg and then go to the admin interface,
get to the screen where you can edit the Philosophy guide and in the field
'image filename' type in 'socrates.jpg'.



B. Other features

There's an "EZLink" feature for those who don't speak HTML. An example:
To create a link to Yahoo from the text of a guide, a librarian can enter
this text:

  {Yahoo, http://www.yahoo.com/} is a broad, general directory of web
  resources.

This will be parsed by ResearchGuide into an HTML link:
  <a href="http://www.yahoo.com/">Yahoo</a> is a broad, general directory
  of web resources.

The reason for this feature was so that librarians with absolutely no
HTML experience could insert links without having to worry about
HTML syntax.  Regular HTML can also be incorporated into these pages.





IV. Call for developers

If you are interested in contributing to future development of the ResearchGuide application, please e-mail kslibner "at" users.sourceforge.net


-end-