[DiscussIt! version 1.0]

DiscussIt! is a free module for the Caudium 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:
  Bill Welliver
  50 Yocum Road
  Wapwallopen, PA 18660 USA

[What's New]

Version 1.0:	
	DiscussIt! 1.0 is now only compatible with Caudium 1.3/4.
	Utilizes the new Caudium user database system, eliminating the
	  need for an external user table.
	Anonymous posts are allowed.
	<forum_link> added for creating custom lists of forums.

Version 0.97:	
	DiscussIt! now quotes any input from the tag or user in order to 
	  minimize security exposures.
	New argument added to the forum tag: quiet.

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.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 (v1.0)
	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 SQL URL, like this:

  mysql://user:password@host/databasename

The tables that DiscussIt! creates are: forum_names, 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.
  quiet			Do not display messages if there are no posts to 
				be displayed
  no_html		Replaces all < and > with &lt; and &gt;.
  nofollowups		Don't show followup discussion with posts.

[Creating a Custom Index]

DiscussIt! does not currently support "nested" forums; that is, forums 
that are grouped together and displayed separately from those in other 
groups. However, you can create pages that contain links to one or more 
forums thereby simulating a "group of forums". To do this, you can use the 
<forum_link> tag. Basically, this tag takes two inputs: the id of the 
forum you wish to create a link for and b) a URL or relative path to a 
page that contains a <forum> tag.

Example:

  <forum_link id="5" href="forumview.html">

might generate the following:

  <a href="forumview.html?forumid=5">Forum Name</a> (5 posts, 2 unread)

depending on the actual identity of forum ID 5.

[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 Caudium's user database and 
authentication system. In order to post, a user must be authenticated. 
This can be done using .htaccess, or any of a number of other methods, 
including RXML.

[Acknowledgments]

Thanks to Xavier Beaudouin <kiwi@oav.net> for his assistance in adding
new features to DiscussIt!.

Bill Welliver <hww3@riverweb.com>
3/10/2004
