                             DOCUMENTATION

         WebBBS 2.25 by Darryl C. Burgdorf (burgdorf@awsd.com)

                    http://awsd.com/scripts/webbbs/

              ===========================================

WebBBS is, as the name implies, a Web-based bulletin board.  Unlike
most other such boards, though, WebBBS stores messages as simple text
files and creates HTML pages "on the fly."  This means that the message
index can be tailored by the user based on date and/or subject (via
built-in keyword search capability), and can be viewed as either a
chronological or a threaded list.  It also means that administration is
a breeze!  WebBBS supports automatic quoting of message text and e-mail
notification of those who want to know immediately when a new message
has been posted.  It also offers an archive-only option and "cookie"
support!

              ===========================================

The files that you need are as follows:

webbbs.pl:  This is the main program file.  You don't actually need
  to do anything to it; in fact, you don't even have to execute it.

config.pl:  This is the configuration file.  Most everything you need to
  change or modify is contained here.  This is also the file that you
  will execute.  (Things are set up this way so that you can effectively
  maintain multiple discussion boards just by keeping separate config
  files for each.)

Basic setup is very simple.  You need only to create a directory in
which the script will store the BBS files, and make sure that it is
set world-writable.  All the actual data files used by the script will
be created for you.  The main program can be put wherever you like.
(Just be sure that the configuration file "requires" it correctly.)
The configuration script can be placed either in the BBS directory
itself (as "index.cgi") or in your CGI-BIN directory.  Since the
configuration file is what you will reference from your Web browser,
the former option allows for "better" URLs (for example, something like
http://www.foo.com/bbs/index.cgi).  However, some systems require that
CGI scripts be in the CGI-BIN directory.

As noted above, the WebBBS configuration file, and not the WebBBS
program itself, should be executed.  The configuration file should, of
course, be set executable.  Make sure that the first line of the script
matches the location of your system's Perl interpreter and that the
"require" line points correctly to your main WebBBS script.  As well,
the following variables need to be defined:

$dir:  The absolute path (minus a trailing slash) of the directory
  in which all the WebBBS files are stored.  This directory must be
  set world readable and world writable!

$cgiurl:  The URL address of the WebBBS configuration script.  If your
  server setup allows it, it is probably most efficient to name this
  file "index.cgi" (rather than the default config.pl) and put it in
  the same directory ($dir) as the rest of the WebBBS files.

$bodyspec:  Any attributes (BACKGROUND, BGCOLOR, TEXT, etc.) which
  should be assigned to the <BODY> tag in message posts.

$HeadLinesFile:  An optional text file containing any HTML code to be
  inserted within the <HEAD> section of the pages produced by the
  script.  This could include, for example, META tags.

$HeaderFile & $FooterFile:  Optional text files containing HTML code to
  be placed immediately following the <BODY> tag and at the very end of
  the BBS index page.  These are included to allow you an easy way to
  give your WebBBS index page the same "look" as the rest of your site's
  pages.  This header and footer are used only on the main message index
  page.

$MessageHeaderFile & $MessageFooterFile:  Optional text files containing
  HTML code to be placed immediately following the <BODY> tag and at the
  very end of the BBS message pages.  You can use the same header and
  footer on these pages as you use on the index page, or use different
  ones, or use none at all.  This header and footer are used on all
  individual message pages, configuration pages, and administrative
  pages.  (In other words, they're used on everything *except* the main
  message index page.)

$DefaultType:  By design, WebBBS index displays default to a simple
  chronological display.  If you prefer the default to be a threaded
  listing, set this variable to "By Threads" instead.  If you prefer
  the mixed-order listing of most Web-based bulletin boards, set it
  to "By Threads, Reversed".  If you want only the first message of
  each thread listed on the index page, set it to "Compressed".

$DefaultTime:  This variable sets the default for the age of messages
  shown in the index list.  If left unspecified, the index will display
  messages posted within the past week.  Valid values are:  "Day"
  "Two Days" "Week" "Two Weeks" "Month" and "Archive".  The latter
  instructs WebBBS to display *all* messages.

$boardname:  The name of your specific discussion board.

$InputColumns & $InputRows:  These variables define the size of the
  text input box for messages.  The default size is 80 columns by
  15 rows.  The smallest allowable size is 25 columns by 5 rows.

$HourOffset:  If you are in one time zone and your Web host is in
  another, you can use this variable to adjust the times shown for
  posts on your BBS.  For example, if your server is located in the
  Eastern time zone, but you're in the Pacific time zone, set it to
  "-3".

$ArchiveOnly:  If this variable is set to "0" the board will function
  normally.  However, if it is set to "1" the message posting form will
  not appear either on the index page or on individual message pages.
  This allows you to set up a "read-only" archive board.  (As a side
  note, if you move files to a new directory from your active board to
  set up such an archive, be sure to use the UNIX "mv" command rather
  than the "cp" command.  This will insure that the file modification
  dates are not altered, so that searches by date will work!)  If you
  enable the admin functions (see below), the administrator will be able
  to post even to a "read-only" board.  This allows you to set up
  "announcement" boards to which you and only you can post.

$AllowHTML:  If this variable is set to "1" people posting messages will
  be able to embed HTML tags (hyperlinks, image references, formatting
  commands, blinking text, etc.) in their messages.  If it is set to "0"
  they will not be able to do so.  Be aware that allowing embedded HTML
  virtually invites abuse of your bulletin board.  Setting the variable
  to "2" will allow any HTML codes to be displayed in the message rather
  than being either interpreted or stripped.  This can be handy, for
  example, if the subject of your BBS is how to code HTML.  SSI commands
  will *never* be interpreted by the script.  If this variable is set to
  "2" they will be displayed along with any HTML tags; otherwise, they
  will simply be stripped.

$AutoQuote:  If this variable is set to "1" the new text of a message
  will automatically be quoted in the message response input box.  If it
  is set to "0" the box will be empty.

$SingleLineBreaks:  WebBBS automatically recognizes a double line break
  or an indentation (either a tab or multiple spaces) as the start of a
  new paragraph.  If this variable is set to "0" any single line breaks
  will be ignored.  If it is set to "1" any single line breaks will be
  converted to <BR> tags.  The former option is usually preferable if
  most posts consist of straight text.  If, however, those posting on
  your board frequently post itemized lists, you may want to use the
  second option, to allow more accurate formatting.

$UseCookies:  If this variable is set to "0" (or commented out) the use
  of "cookies" will not be implemented.  If it is set to "1" it will be.
  "Cookies" allow the board to recognize return visitors, keep track of
  messages posted since their previous visit, maintain their personal
  index display preferences, and automatically insert their names and
  e-mail addresses into the post forms.  IN ORDER FOR "COOKIE" SUPPORT
  TO WORK, you must first install Matt Wright's "cookie.lib" (available
  from <http://www.worldwidemart.com/scripts/>).  If you're not using
  "cookie" support, comment out the "require" line in the configuration
  script.  Otherwise, make sure it points to the correct location on
  your system of Matt's "cookie" library.

$UseAdmin:  If you set this variable to "1" you'll be able to access
  the admin function and delete any or all posts in bulk.  (See below.)
  It will also allow you to post to archive ("read-only") boards.
  If you leave variable unassigned, the admin function will be disabled.
  (This will *not* prevent you from using the automatic "reaper"
  function.)  IMPORTANT NOTE: If you activate the admin function, be
  sure to load the admin page immediately and set a password!  If you
  don't, someone else might come along and do it *for* you....

$Max_Days & $Max_Messages:  By setting one or both of these variables,
  you instruct WebBBS to automatically purge message files for you.
  (This is the "reaper" function mentioned above.)  For example, if you
  set $Max_Days to "7" any messages which have been sitting idle for
  over a week will be deleted, and if you set $Max_Messages to "200"
  you will never have more than 200 messages in your index.  If you
  set both variables, older messages will be deleted first, and then
  more recent messages will be deleted if necessary to bring the total
  number within your prescribed limits.

$ArchiveDir:  If instead of being deleted, you want "expired" messages to
  be moved into another directory (for example, for use in a "read-only"
  archive board), define this variable with the full path to the directory
  in question.  This will replace the "reaper" function with a "harvester"
  function, which will remove the old messages from your active board by
  moving them rather than by deleting them.

$AllowUserDeletion:  Set this to "1" if you want users to be able to
  include a password with their messages which will allow them to come
  back and delete them on their own.  Leave it undefined if you want
  them to be stuck with what they posted.

$AllowEmailNotices:  Set this to "1" if you want users to be able to
  request e-mail notifications whenever someone responds to their
  messages.  Leave it undefined if you want to require them to actually
  visit the BBS again to find out.  This ONLY defines whether or not
  people can request automatic notifications of responses to their own
  posts, and is distinct from the $email_list variable (below), which
  defines what, if any, new post "subscription" capability your board
  will support.  Like the other e-mail functions, the automatic
  notification of responses will be disabled if you do not define
  the $mailprog variable.

$AllowPreview:  Set this to "1" if you want your users to be able to
  "preview" their posts before actually submitting them.

$AllowURLs:  Set this to "1" if you want users to be able to include
  a URL link at the bottom of their messages.  (This can be handy if
  you don't allow HTML in posts, and can even be nice if you *do*
  allow it.)

$AllowPics:  Set this to "1" if you want users to be able to include
  a link directly to a graphic image on their own or another server.
  Depending upon the nature of your BBS and the demographics of your
  audience, of course, you very well may not want them to be able to
  post unapproved graphics....

$NaughtyWords:  If you want certain words to be "censored" in posts to
  your BBS, simply list them here (separated by spaces).  Any words (or
  character strings) matching the contents of this variable will be
  replaced by a string of hash marks in the actual post.  For example,
  if you defined this variable as "this that" and someone attempted to
  post the message, "This is one thing, that is another," the actual
  post would appear as "##### is one thing, ##### is another."

$mailprog:  The absolute path to your system's sendmail program.  If
  your system doesn't have "sendmail" or if you simply don't want the
  various e-mail notification functions activated, leave this variable
  unassigned.

$maillist_address:  The address you wish to use for e-mail related to
  your BBS.  (Note that e-mail notifications will be addressed *from* a
  "dummy" address, and that the address you've designated here will
  appear in the body of the message.  This is done in an attempt to
  prevent people from trying to respond to the e-mail notifications
  instead of posting their responses directly to the BBS.)  The "@"
  character in your address must be "escaped" with a backslash
  (e.g., "scripts\@awsd.com").  Note that this variable should be
  assigned even if you don't enable the various e-mail notification
  functions, since the maillist address is also shown on some of the
  BBS's admin pages to let people know how to contact you if they have
  any problems.

$email_list:  If you don't want to set up any sort of e-mail list to
  notify interested parties of new posts, simply leave this variable
  unassigned.  If you have a relatively low-volume board, and want to
  allow people to get e-mail copies of any messages immediately as they
  are posted, set it to "1".  If you want to set up a digest-style
  notification list, set it to "2".  Note that the digest mailings are
  *not* handled by the WebBBS script itself; if you want to send out
  that sort of notification, you'll also need to set up the separate
  WebBBS Digest script available from the WebBBS "Examples and Extras"
  page <http://awsd.com/scripts/webbbs/examples.html>.

$HeaderOnly:  If you set this variable to "1", any e-mail notifications
  will contain only the header information, and not the main body of the
  post.  This is handy if you want to be able to let people know when
  new messages are posted, but still want them to have to come to the
  BBS itself to *read* thos messages.  Note that this setting will not
  effect the manner in which digests are sent out; if you're using the
  digest option, the e-mail notices will *always* contain the full text
  of the messages posted.

$AdminEmail:  If you want to receive notice of new messages yourself
  (at the $maillist_address defined above), but don't want to set up
  a subscription list to allow others to get such notifications, set
  this variable to "1".

              ===========================================

ADMIN FUNCTIONS

The admin index, from which you can easily delete any or all of the
messages on your board, is accessed by adding "?admin" to the URL of
your message index.  For example, if your board index's URL was
"http://foo.com/index.cgi" you'd type "http://foo.com/index.cgi?admin".

The first time you access this index, you should be sure to use the
"change password" function to *set* a password.  (For the first time
only, you can type anything or nothing in the "old password" box.)

Note that *regardless* of whether or not you've enabled the admin
delete capability, users will still be able to delete their own
posts if they've assigned passwords to them (assuming, of course, that
you've allowed them the option).  The admin password, if enabled, will
also allow individual deletion of *any* post.

              ===========================================

E-MAIL NOTIFICATION LISTS

WebBBS is not designed to handle very large e-mail notification
lists, and the basic notifications are frankly not handled in the most
efficient manner possible.  If your notification list starts to get
large (several hundred addresses), you will notice a significant lag
time in the processing of postings.  Before that happens, you should
switch from the basic "as messages are posted" notification scheme to
the more efficient digest setup.

              ===========================================

USING WEBADVERTS WITH WEBBBS

If you're using WebAdverts to display advertising banners on your site,
and want to display banners on your BBS pages as well, you'll need to
define the "require" line and the first two variables ($adverts_dir and
$display_cgi) in the "insert adverts" subroutine at the end of the
configuration file to match the same lines in your WebAdverts
configuration file.

Once that is done, you can include banners anywhere in your header or
footer files simply by insert the comment line "<!--InsertAdvert (zone
name)-->" wherever you want a banner to appear.  Note that the zone name
itself is optional; if you want a banner displayed without regard to
zones, or if you're not using zones, you can leave out the
specification.

              ===========================================

This documentation assumes that you have at least a general familiarity
with setting up Perl scripts.  If you need more specific assistance,
check with your system administrators, consult the WebScripts FAQs
(frequently-asked questions) file <http://awsd.com/scripts/faqs.shtml>,
or ask on the WebScripts Forum <http://awsd.com/scripts/forum/>.

-- Darryl C. Burgdorf

