[DiscussIt! version 0.95]

DiscussIt! is a free module for the Roxen Web Server. It allows easy
creation of discussion groups without the need to program custom CGI
scripts.

Please remember that this is a work in progress. Your comments and
suggestions are appreciated. You can send your comments to me, the
developer at hww3@riverweb.com.

If you find this module useful, I'd greatly appreciate a postcard from you
letting me know you're out there. My Address is included in the
distribution.

Also, be sure to read the file LICENSE, included with this module.

[What's New]
Version 0.96:
	DiscussIt! works with Caudium 1.2, Roxen 2.2 and Pike 7.2.
	
Version 0.95:

	DiscussIt! works with Caudium and Pike 7.0.
	Fixed a potential security hole that allows HTML in posts.

Version 0.9:

	Initial release of module.

[Requirements]

   * Caudium 1.0, Roxen 1.3 or higher.
   * RDBMS supported by Roxen (mySQL is known to work, others may also)

[Getting DiscussIt!]

   * Download the latest version of DiscussIt! with Documentation (v0.95)
	from http://www.riverweb.com/modules/dist/

[Installing DiscussIt!]

Using DiscussIt! is simple! Just download the archive, then unpack it by
using the following command:

        tar -zxvf discussit-1.0.tar.gz

You should get a directory called discussit-1.0. Inside that directory is
a file called discussit.pike. Copy that file to your Roxen modules
directory, under roxen/server/modules, or another directory that has been 
added to your module search path. Then you can use the Configuration
Interface to add the DiscussIt! module. You may need to flush your module
cache n order to see the new module depending on how Roxen is installed on
the system in question.

There are a few options you can change, but in most cases, you will only
need to tell DiscussIt! about the database you want to use for storing the
discussion groups. This database should already exist. DiscussIt! will
create the tables it needs when it is loaded the first time.

You must specify your database using a Roxen SQL URL, like this:

  mysql://user:password@host/databasename

The tables that DiscussIt! creates are: forum_names, users, read_entries
and articles. These tables should not already be in use by another
application. If they are, DiscussIt! may not be able to find the proper
fields in order to operate.

Note for non-MySQL users: If you are not using MySQL as your database
server, you may find that DiscussIt! uses bad SQL for your server.
Postgres is known to have a problem with the SQL in DiscussIt!. An
untested patch is included in the distribution, called
discussit.pike.patch. Your mileage may vary when using this patch. If you
make changes to the patch to get DiscussIt! to work with your database,
please send updates to the author, whose email is listed below.

That's all there is to it! You can now start using the features of the
DiscussIt! module.

[Using DiscussIt!]

There are 3 components of a working DiscussIt! application:

   * The DiscussIt! Module (you've already installed it)
   * An DiscussIt! administrator's page
   * A DiscussIt! access page

[The Administrator's Page]
The administrator's page is where you can create and delete forums,
delete posts, and do other administrative tasks. You can use any text or
HTML editor you'd like to create this page. Since this page can be used
for evil as well as good, you should make sure this page is protected by a
password or some other security measure.

On this page, you simply need to add the following tag:

<forum_admin>

And DiscussIt! will handle the rest.

[The DiscussIt! Access Page]
The DiscussIt! Access Page is simply an HTML file that includes the
DiscussIt! access tag. The tag that handles all of the dirty work is:

	<forum>

Simply place this tag on the page you would like to access your forums
from. DiscussIt! will handle the rest.

The forum tag takes the following attributes:

  forum=value		Display only forum value (the numeric forum id).
  name=value		Forum's name (used when autocreating forums).
  description=value	Forum's description (for autocreate).
  noindex		Don't display a list of all available forums.
  loud			Display a message indicating an empty forum.
  no_html		Replaces all < and > with &lt; and &gt;.
  nofollowups		Don't show followup discussion with posts.

[Autocreate]
If you have enabled the "autocreate" function in the module's
configuration, DiscussIt! will try to create new forums when provided with
a forum tag with a name attribute that doesn't already exist.

[Posting Access]
Access to adding new posts is controlled by the "users" table. In order to
post, a user will be prompted for a username and password. This
information will then be matched against data in the "users" table. To
grant access to a user, simply add a record to this table with a password.
The password is stored in clear text at this time.

Example using (My)SQL: 

  INSERT INTO users VALUES(NULL, 'user','mypasswd','Joe User', 
    'myself@me.com',NOW());

DiscussIt! determines whether a user is logged in by the presence of the
"userid" cookie. The cookie contains the numeric userid of the currently
logged in user. You may set this cookie ahead of time to eliminate the
need to log in when using DiscussIt!, or you may use this information to
create an "anonymous user" that allows posting without logging in. To do
this, simply create an entry in the users table for the anonymous user,
then set the userid cookie with the numeric userid of that user.

[Acknowledgments]

Bill Welliver <hww3@riverweb.com>
2/8/2001
