                             DOCUMENTATION

         WebBBS 4.33 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 threaded,
chronological or "guestbook-style" lists.  A wide variety of options
are available both to the administrator and to the users, and "behind-
the scenes" administrative tasks (editing and deleting of messages,
etc.) are 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,
the ability to run moderated boards, and "cookie" support!

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

The files that you need are as follows:

webbbs_basic.pl, webbbs_form.pl, webbbs_index.pl, webbbs_misc.pl,
  webbbs_post.pl, webbbs_profile.pl, webbbs_read.pl and
  webbbs_rebuild.pl:  These are the "pieces" of the main program file.
  You don't actually need to do anything with them; the appropriate
  segments will be called by the configuration script depending upon
  what specific action the script is supposed to perform.

webbbs_settings.pl:  The "master" configuration file. In this file,
  you define the bulk of your configuration settings.

webbbs_config.pl:  This is the specific configuration file for a
  particular board.  In this file, you define those configuration
  variables unique to the particular board in question. This is also
  the file that you will execute.  (You can easily maintain multiple
  discussion boards just by keeping separate config files for each.
  You do *not* need multiple copies of the main script files.)

webbbs_text.pl:  A simple file containing the text of messages included
  on various pages by the program.  They're separated to make alteration
  or translation a bit easier.

sproxy.cgi and spch.js:  The two files needed to interface WebBBS with
  the SpellChecker.net system.

Basic setup is very simple.  You need only to create a directory in
which the script will store the message and other data files, and make
sure that it is set world-writable.  The script files can be put
wherever you like (or wherever your system administrators require them
to be).

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.  As well, a number of variables need to be defined.
Note that *only* the variables in the configuration script and in the
first section of the "settings" script need to be changed from their
default values.  If you're not sure you know what you're doing, don't
even bother looking at any other of the configuration settings until you
have your file paths and e-mail variables defined correctly, and have
verified that the script is indeed functioning!

(A) The essential variables are as follows:

In the config script itself, first make sure that the "require" line
is defined with the correct path to your webbbs_settings.pl file.  Then
define the following variables:

$dir:  The absolute path (minus a trailing slash) of the directory
  in which all the WebBBS data files are to be stored.  This directory
  must be set world-writable, or else WebBBS won't be able to use it!

$cgiurl:  The URL address of the WebBBS configuration script itself.
  (In other words, it should contain the URL to be referenced to run
  the script!)

$boardname:  The name of your specific discussion board.  THIS VARIABLE
  MUST BE DEFINED FOR COOKIES AND CERTAIN OTHER SCRIPT FUNCTIONS TO
  WORK PROPERLY!  If you don't want the board name to print, set
  $printboardname as 0.  Do *not* simply leave $boardname undefined.

$shortboardname:  You can optionally define here a shorter version of
  your forum's name, to be used in the subject lines of any e-mail
  notices sent out announcing new posts.  (If this variable is not
  defined, your forum's full name will be used.)

Under the third heading ("Define variables you want changed from
webbbs_settings.pl"), simply re-define any of the variables from the
"settings" script which, for whatever reason, should be different for
this particular board.  (If you're only *running* one forum, obviously,
this is a moot point.  But if you're running multiple boards, while many
settings will be consistent from one to another, other settings, such as
the forum name, will be different in each case.)

Once you're done with the webbbs_config.pl script, you'll need to define
the following variables in webbbs_settings.pl:

$scripts_dir:  This is the directory in which all of the script files
  reside.  (They don't *have* to all be in a single directory, but it's
  certainly simpler if they are.)  As you did when you defined the data
  directory, be sure to define this variable with a *path*, and not
  with a URL.  Note that this directory, unlike the data directory
  defined in your config script, does *not* have to be world-writable.

$webbbs_basic, $webbbs_form, $webbbs_index, $webbbs_misc, $webbbs_post,
  $webbbs_profile, $webbbs_read, $webbbs_rebuild and $webbbs_text:
  These variables define the specific locations of the various "pieces"
  of the WebBBS script.  If they all reside in the directory defined
  in $scripts_dir, and have not been renamed, then you do *not* need
  to alter the default definitions.

$mailprog:  This variable defines what, if any, mail program is to
  be utilized by the script.  It can be defined in one of three ways.
  The prefered definition is the absolute path to the "sendmail"
  program, at least if you're on a server that *has* it.  (NT servers
  do *not*.)  Note that this is *not* the same as the "mail" program,
  and has absolutely nothing to do with Matt Wright's "formmail" or any
  other CGI script.  If your system doesn't have "sendmail," you can
  instead define the variable as "SMTP" to instruct WebAdverts to access
  your server's mail server directly.  Finally, if it's available to
  you, you can utilize Libnet's "Net::SMTP" Perl module by defining the
  $mailprog variable as "libnet".  If you simply don't want the various
  e-mail notification functions activated, leave this variable
  unassigned.

$WEB_SERVER & $SMTP_SERVER:  If you're using a direct SMTP interface,
  you can define either or both of these variables with the relevant
  server names.  If you leave them undefined, the script will attempt
  to determine for itself what the names should be.  If you're using
  sendmail, of course, these variables are irrelevant.

$admin_name:  The name of your board's administrator.  It will appear
  at the bottom of script-generated pages with an e-mail link (using
  $maillist_address, below).
  
$maillist_address:  The address you wish to use for e-mail related to
  your 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.

$notification_address:  If you send out e-mail notices, they will be
  addressed "From:" the $maillist_address above, and "To:" the address
  defined here.  If you don't want to receive copies of all the notices,
  define this with a dummy value.  If you *do* want to receive copies,
  define it with a real address (such as your administrative address
  already defined above).  Please note that by "dummy value" I do *not*
  mean that you should send the notices to someone else's domain!  Set
  up an address within your own domain which automatically deletes
  incoming mail!

$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 download page.

$private_list:  If you want e-mail notices to be sent out, but *don't*
  want just anyone visiting your board to be able to subscribe, set
  this variable to 1.  (Setting this variable to 1 but leaving
  $email_list set to 0 is an easy way to ensure that the administrator
  gets copies of each post, even if no one else does.)

$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.

If you're utilizing the direct SMTP interface rather than the "sendmail"
program, uncomment the "use Socket" line in the config file.  (In other
words, remove the initial hash mark symbol.)  Otherwise, just leave it
alone.

If you're using the "Net:SMTP" module, uncomment both the "use Net:SMTP"
line and the "use Socket" line.

(B) The optional configuration variables are as follows:

As noted above, the rest of the variables do *not* have to be altered
from their default values.  If you're not quite sure what you're doing,
don't change any of them until you actually have the script running,
and are ready to begin "fine-tuning" it.

$DBMType:  This variable determines how the DBM (database) file used
  for storage of index information will be accessed.  Most users can
  leave it set to 0.  If the script can't open the database file,
  though -- and especially if you receive "Inappropriate file type
  or format" errors -- try setting it to 1.  This will replace the
  basic tie() command with a version of the command specific to the
  DB_File module, which produces the above error message.  If all
  else fails, set $DBMType to 2, and instead of tie() commands, the
  more generic (but less efficient) dbmopen() commands will be
  used.

(The "BEGIN { @AnyDBM_File::ISA = qw (DB_File) }" line is explained
later; unless you're going to try to use something other than your
server's default DBM module, you don't need to worry about it.)

The following four variables allow you to add "spell checking" 
functionality to your forum.  This is done by interfacing WebBBS
with the SpellChecker.net system.  The two "special" files you
need are included with the WebBBS distribution, and Jeff Bianco of
SpellChecker.net has kindly established a "generic WebBBS user" ID,
so you don't even need to visit their site directly.  However, if
you want to do so, you are certainly welcome to!  Registering to
get your own ID (which might be necessary, for example, if you want
to spell check documents in a language other than English) doesn't
cost anything, unless you opt to subscribe to their "bannerless"
version of the system.  (Normally, banners are shown in the spell
check box as your visitors "clean up" their messages.)  Their site
can be found, logically enough, at http://spellchecker.net.

$SpellCheckerID:  Define this variable with the ID number you
  received from SpellChecker.net.  The default value of "0532115747"
  has been set up as a "generic WebBBS user" account, and will work
  for you, but if you have your own ID, you really ought to use it,
  instead.

$SpellCheckerPath:  This variable should be defined with the path
  to your "sproxy.cgi" CGI script.  Note that this "path" isn't a
  true path, as are the paths elsewhere in the WebBBS configuration,
  but rather, is the path portion of the file's URL.  In other words,
  if the URL of the file is "http://foo.com/cgi-bin/sproxy.cgi," you
  need to define this variable as "/cgi-bin/sproxy.cgi."  It's a bit
  confusing, yes, but I have no control over it.  ;)  Make sure the
  first line of the file points correctly to your Perl interpreter,
  and make sure the file is set world-executable!

$SpellCheckerJS:  Each page on which a form exists to be spell-checked
  must reference a bit of JavaScript code.  Once, this code resided on
  the SpellChecker.net server; however, the need to reference their
  server resulted in slowdowns on busier forums.  To help alleviate
  this problem, the good folk at SpellChecker.net have made it possible
  to download the JS file ("spch.js") to your own server.  That file is
  included in the WebBBS distribution, along with the sproxy.cgi file.
  If you want to use it, define here its URL (*not* its path).  (If you
  don't want to use it, leave this variable undefined, and WebBBS will
  simply have your pages reference the SpellChecker.net server as in
  the old days.)  Please note that this file does *NOT* seem to work if
  placed in your CGI-BIN directory or in another normally-inaccessible
  directory!
  
$SpellCheckerLang:  Define here the default language to be used in the
  spell checking.  (For most WebBBS users, that will of course be "en"
  for English.)

The next three variables concern "user profiles," which you can, if
you like, allow your forum's visitors to create.  These profiles will
be more-or-less permanent features of your forum.  A particular user's
profile will be accessible from any messages he posts, and will allow
him to tell other visitors a bit more about himself than is evident
from his messages.  A user can update his profile whenever he likes.
The administrator can also edit or delete profiles easily, as all
profiles are accessible from the administrative script's "poster
stats" menu option.

$UserProfileDir:  If you want to allow your visitors to create user
  profiles, define here the path (not the URL) of the directory in
  which the profile files should be stored.

$UserProfileURL:  If you want to allow your visitors to upload graphic
  images to your server to be included with their profiles, define here
  the URL corresponding to the directory defined in $UserProfileDir.
  (Graphic images will be stored in the same directory as the profile
  files themselves; the URL is necessary, of course, for *access* to
  the graphics.)  If you do *NOT* want to allow users to upload files
  to your server, simply leave this variable undefined.  You do *not*
  have to allow file upload in order to allow your users to create
  profiles.

$MaxGraphicSize:  If you're allowing file uploads, define here the 
  maximum size (in kilobytes) of the graphic files that can be uploaded.

$MetaFile:  The path to a text file containing any HTML code (META tags,
  etc.) to be inserted within the <HEAD> section of the pages produced
  by the script.

$HeaderFile & $FooterFile:  The paths to 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:  The paths to text files,
  similar to the above, containing code to be placed at the top and
  bottom 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.)

$SSIRootDir:  Your header and footer files can contain SSI "include"
  tags.  If they do, you need to specify in $SSIRootDir the path which
  should be prepended to the "include" definition, in order to define
  the file's full path and thus allow the script to find it.

$bodyspec:  Any attributes (BACKGROUND, BGCOLOR, TEXT, etc.) which
  should be assigned to the <BODY> tag in message posts. Do *not*
  include in this variable a full <BODY> tag; include only the contents
  *of* the body tag.
  
$fontspec:  Any attributes (FACE, etc.) which should be assigned to
  a page-wide <FONT> tag.  Table cells will also be defined with the
  same <FONT> tag, so that the page presents a uniform appearance even
  in Netscape Navigator, in spite of the fact that that browser is too
  stupid to realize that global <FONT> specifications *should* apply
  inside tables as well as outside of them.

$navbarspec:  The attributes (BORDER, BGCOLOR, etc.) to be used in
  the table containing the "navigation bar" at the tops and bottoms of
  your pages.

$navbarfontspec:  Font specifications specific to the nav bar.

$tablespec:  The attributes (BORDER, BGCOLOR, etc.) to be used in
  the tables used by the script for the "post form" boxes.

$tablefontspec:  Font specifications specific to the above tables.

$ListBullets:  By default, WebBBS (as of version 4.20) creates its
  index listings with "unbulleted" lists, using the <DL> and <DD>
  HTML tags.  If you prefer "bulleted" lists, set this variable to
  1, and the script will instead use the <UL> and <LI> tags.

@SubjectPrefixes:  An optional list of "mandatory" subject prefixes.
  If you've defined anything here, those posting on your forum will
  have to pick one of your options, which will precede whatever they
  enter as the subject of their message.  For example, if you want
  an easy way to tell business-related from personal messages on your
  forum, you might use "@SubjectPrefixes=('Business:','Personal:');"
  so that all message subjects end up beginning with either
  "Business:" or "Personal:".

$MessageOpenCode and $MessageCloseCode:  These variables should be
  defined with any HTML code you want to appear before and after the
  text of messages.  They can be used, for example, to place message
  text within <BLOCKQUOTE> tags, or to highlight the text with a
  different font and/or color than is used on the rest of your site.
  $MessageCloseCode should, of course, contain "closing" tags for
  whatever $MessageOpenCode opened.

$NewOpenCode and $NewCloseCode:  These variables should be defined
  with any HTML code that you want to have appear before and after
  "new" messages in the index listings.  By default, a red "NEW:"
  will show up preceding the message subject in the index listing.
  You might want to change it to call a graphic image, for example.
  
$AdminOpenCode and $AdminCloseCode:  Very similar to the above, these
  variables should be defined with any HTML code that you want to have
  appear before and after admin posts in the index listing.

$UseLocking:  Under most circumstances, this variable should be defined
  as 1.  Set it to 0 only if, for whatever reason, your server doesn't
  support the flock() command.  (If this variable is set to 0, a
  semaphore-based file locking will be used instead of flock(); while
  it works reasonably well in most situations, it isn't nearly as
  efficient.)

$RefreshTime:  The number of seconds that the various "admin" screens
  ("Your message has been posted," etc.) will wait before sending a
  visitor back to the main index.  If you're displaying banners on the
  pages, you'll probably want to set this fairly high; otherwise, set
  it low so that your visitors don't have long waits.  If you define
  this variable to 0, the pages will *not* auto-refresh at all.
  
$UseFrames:  This can either be set to "horizontal" (or "horiz" or "h")
  if you want an upper frame for the message index and a lower frame for
  message texts, set to "vertical" (or "vert" or "v") if you want side-
  by-side frames, or left undefined if you don't want to use frames at
  all.

$BBSFrame:  If you're using WebBBS with frames within another frameset,
  you'll want to define this with the name of the frameset in which
  WebBBS is being displayed.  (The default definition of "_parent"
  might also suffice, depending upon your setup.)

$WelcomePage:  If you're using WebBBS with frames, you can define this
  variable with the URL of a page you want to appear initially in the
  WebBBS "message" window (which otherwise will initially be blank).

$Moderated:  If you set this variable to 1, any new posts will be put
  "on hold" until approved by the administrator, rather than being
  posted publicly immediately.  Note that in order to run a moderated
  board, you *must* have registered WebBBS and obtained the
  administrative script, as without it, you'd have no way of
  approving the posts!

$SearchURL:  Generally speaking, this variable should be left undefined,
  as the search facilities built into WebBBS are quite sufficient for
  most any purpose.  However, if you've got a site-wide search facility
  which includes the message content of your forum(s), and you prefer
  that all searches be conducted through it, you can define this variable
  with its location.  Anyone clicking on the "Search" option on a WebBBS
  page will then be taken to *that* search form, rather than the one
  generated by WebBBS itself.

$TopNPosters:  If this is defined (with a number), visitors to your
  bulletin board will be able to access a list showing who's posted
  the most messages.
  
$Navbar_Links:  You may use this hash variable to define the names
  and URLs of "extra" links you'd like to have appear in the main index
  page navigation bar.  These could be links to FAQs or policies pages,
  a link to an archive board, a link back to your main page, or anything
  else you find relevant.  You can specify a TARGET destination for the
  link by appending it to the URL, separated by a "pipe" (|) character.
  If you do *not* specify a TARGET, the link will open in the window
  used for display of messages.  The example below would put two new
  links on the navbar: a link to a "welcome" page, which would be
  loaded (by default) in the message window, and a link to a "help"
  page, which would be loaded in the full browser window.
  
    %Navbar_Links = (
      'Welcome','welcome.html',
      'Help','help.html|_top'
      );

$SepPostFormIndex and $SepPostFormRead:  These variables determine
  whether "post message" forms will appear on the main index page and/or
  the individual message pages, respectively.  Values of 0 instruct the
  script to include the forms as part of the pages; values of 1 instruct
  it to have those forms appear on pages by themselves.  If you're using
  frames, these variables are automatically set by the script to 1, to
  ensure that the post forms appear in full windows and can thus be
  more easily used.

$DefaultType:  By design, WebBBS index displays default to a simple
  chronological display.  If you prefer a different style, define
  it here.  The available options are "Chronologically",
  "Chronologically, Reversed", "Alphabetically", "Alphabetically,
  Reversed", "By Threads", "By Threads, Reversed", "By Threads, Mixed",
  "Compressed", "Compressed, Reversed", "Guestbook-Style", 
  "Guestbook-Style, Reversed", "Guestbook-Style, Threaded",
  "Guestbook-Style, Threaded, Reversed" and
  "Guestbook-Style, Threaded, Mixed".

$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 two weeks.  It can be defined with
  whatever value you like, such as "2 Day(s)", "3 Week(s)" or even
  "10 Month(s)".  Note that the format of the definition must match
  that seen on your forum index page.

$PaginateGuestbook:  If you or your users utilize the "threaded
  guestbook" listing style (in which the full text of all messages in
  a given thread is displayed), you can define here the maximum number
  of posts which will appear on a single page.  If you don't use that
  listing style, or don't have a lot of long threads, you can simply
  leave it defined as 0, so that *all* messages are displayed.

$printboardname:  If this variable is set to 1, the board name
  defined above will be included at the top of the script-generated
  pages.  If the variable is set to 0, it won't be.  This allows you
  to avoid duplication if you're using a graphic image in your header,
  for example, as a title.

$DateConfig:  A string defining the format in which you want dates to
  appear on the board.  The following codes are available:

    %mo% = month (numeric)
    %MO% = month name (as defined in webbbs_text.pl)
    %dy% = day of month (numeric)
    %DY% = weekday (as defined in webbbs_text.pl)
    %yr% = year (two-digit)
    %YR% = year (four-digit)
    %am% = either "a.m." or "p.m."
    %sc% = seconds (two-digit)
    %mn% = minutes (two-digit)
    %hr% = hour (12-hour clock)
    %HR% = hour (24-hour clock)

  So, for example, "%mo%/%dy%/%yr% %HR%:%mn%" would display dates as
  "7/22/00 15:30"; but "%DY%, %dy% %MO% %YR%, at %hr%:%mn% %am%" would
  display as "Wednesday, 22 July 2000, at 3:30 p.m."

$IndexEntryLines:  This variable defines the format in which the index
  should be displayed.  Defining it as 1 gives each entry a single line,
  while defining it as 2 gives each entry two lines.  (The latter is
  the better bet if you're using a longer date format and/or displaying
  extra information such as IP addresses or view counts.)  You can also
  define the variable as "news" in which case the index will be
  displayed in a tabular format similar to that utilized by many
  Usenet newsreaders.

$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.  With the
  administrative script (see below), of course, 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.  (See
  also $AllowNewThreads and $AllowResponses, below.)

$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.

$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.

$AutoQuoteChar:  This defines the character you want used at the
  beginning of "quoted" lines.

$AutoHotlink:  If you set this variable to 1, the script will attempt
  to "automatically" hotlink any URLs or e-mail addresses included in
  the body of a message.  (As of WebBBS version 4.20, auto-hotlinking
  and the allowing of HTML code in messages are no longer mutually
  incompatible features.  The two can now co-exist harmoniously.)

%SmileyCode:  This variable defines a list of "codes" which will be
  automatically converted when they appear in the subject or body of
  a message.  It can be used, for example, to replace certain ASCII
  "smilies" with graphic images.  (Hence, the variable's name.) The
  example below instructs the script to replace a variety of ASCII
  "faces" with appropriate graphics.  Note that the backslash (\)
  must be "escaped"; in other words, if you want to use it, use two
  in a row instead of just one.  (If you don't, the script will not
  run.)

    %SmileyCode = (
      ':)','<IMG SRC="smile.gif" BORDER=0 ALT=":)">',
      ':(','<IMG SRC="frown.gif" BORDER=0 ALT=":(">',
      ':O','<IMG SRC="oh.gif" BORDER=0 ALT=":O">',
      ':D','<IMG SRC="biggrin.gif" BORDER=0 ALT=":D">',
      ';)','<IMG SRC="wink.gif" BORDER=0 ALT=";)">',
      '8)','<IMG SRC="glasses.gif" BORDER=0 ALT="8)">',
      ':b','<IMG SRC="tongue.gif" BORDER=0 ALT=":b">',
      ':\\','<IMG SRC="ohwell.gif" BORDER=0 ALT=":\\">',
      '>:(','<IMG SRC="../smilies/angry.gif" BORDER=0 ALT="&gt;:(">',
      ':|','<IMG SRC="indifferent.gif" BORDER=0 ALT=":|">'
      );

%FormatCode:  This variable is essentially identical to the above
  variable, except that (a) only text in the body of a message will
  be converted, and (b) the matching for this variable, unlike the
  matching for %SmileyCode, is case-insensitive.  This variable is
  intended to be used to allow certain basic formatting functions to
  made available to your forum's users, even if you don't want to
  let them utilize HTML code directly.  (The reasons for the two
  differences in the way the variables are handled are [a] the fact
  that you probably don't want your visitors leaving formatting tags
  in their message subjects unclosed, and thus fouling up your index
  listings, and [b] the fact that while you probably don't want ":d"
  and ":D" being treated by the script as the same thing, you most
  likely *do* want "[code]" and "[CODE]" treated the same.)  The
  example below provides your visitors with the same formatting
  options available on the WebScripts support forums.

    %FormatCode = (
      '[b]','<STRONG>',
      '[/b]','</STRONG>',
      '[i]','<EM>',
      '[/i]','</EM>',
      '[list]','<UL>',
      '[*]','<LI>',
      '[/list]','</UL>',
      '[quote]','<BLOCKQUOTE>',
      '[/quote]','</BLOCKQUOTE>',
      '[code]','<PRE>',
      '[/code]','</PRE>',
      '[center]','<CENTER>',
      '[/center]','</CENTER>',
      '[big]','<BIG>',
      '[/big]','</BIG>',
      '[small]','<SMALL>',
      '[/small]','</SMALL>',
      '[red]','<FONT COLOR="ff0000">',
      '[/red]','</FONT>'
      );

$NM_Telltale:  An optional bit of text or HTML code to be appended
  to the subject of any message which does not contain any original
  body text.  ("NM" is a standard Usenet/Internet abbreviation
  meaning "no message.")

$Pic_Telltale:  An optional bit of text or HTML code to be appended
  to the subject of any message which includes an image URL.  (On
  forums where many visitors use the "optional image URL" slot just
  to include a banner or other advertisement of their own Web site,
  you'd obviously probably not want to define this variable.  But on
  forums where the presence of pictures in a message is of actual
  significance, the "telltales" can be quite handy, allowing readers
  to quickly find the messages which include such pictures.

$ThreadSpacer:  An optional bit of text or HTML code to be inserted
  between threads in the index listing.  (It can be as simple as a
  <P> tag.)

$GuestbookSpacer:  An optional bit of text or HTML code to be inserted
  between messages in the various "guestbook" style listings.

$DisplayEmail:  If you leave this defined as 1, posters' e-mail
  addresses will be shown on the message display pages (if an e-mail
  address was provided, of course), and it will be possible for those
  reading messages to send private e-mails to the authors.  If you
  undefine this variable, e-mail addresses will *not* be displayed.  If
  you have many users who want to take advantage of the script's e-mail
  notification features, but *don't* want their e-mail addresses seen
  by others, this can be handy.

$ResolveIPs:  If this variable is set to 1, posters' IP addresses will
  be resolved to domain names.  If it is left undefined, they will not
  be resolved.
  
$DisplayIPs:  If this variable is set to 1, posters' IP addresses or
  domain names, as determined by the setting of $ResolveIPs, will be
  displayed (when the index listing or message files are viewed) along
  with their names and e-mail addresses.  (Note that they will be
  recorded in the message files for the administrator's reference,
  regardless of whether or not they're actually displayed to
  visitors.)

$DisplayViews:  If this variable is set to 1, the script will keep
  track of and display in the index the number of times each message
  has been read.  (With version 4.20, the database of view counts has
  been separated from the main index database, so keeping the view
  counting "turned on" should no longer significantly effect a busy
  forum's efficiency.)  If it is set to 0, view counts will not be
  maintained.  If it is set to 2, view counts *will* be maintained, but
  will not be displayed.  (The latter setting might be handy, for
  example, if you want view counts to be available to the administrator,
  but not to just anyone who visits the forum.)

$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.

$MaxMessageSize:  This is the maximum size (in kilobytes) of messages
  which can be posted.  The primary purpose of this variable is to
  prevent users from posting entire book chapters or the full text of
  long CGI scripts....

$MaxInputLength:  This variable defines the maximum length of message
  subjects and author names.

$LockRemoteUser:  If your WebBBS script is password protected via
  .htaccess or another system which sets the "REMOTE_USER" environment
  variable, you can elect to force users to post under their login names
  by setting this variable to 1.  (The variable will be logged and will
  be available to the administrator when viewing messages, even if you 
  don't require that it be used as a posting name.)

$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, 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.

$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.

$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....

$AllowProfileHTML, $AllowProfileURLs and $AllowProfilePics:  These three
  variables work just as do the $AllowHTML, $AllowURLs and $AllowPics
  variables, only they apply (obviously) to user profiles rather than
  to messages.
  
$SaveLinkInfo:  If you set this variable to 1, any information provided
  in the optional link and image fields will be stored in the user's
  cookie file.  If you have a lot of people who use those fields for
  a sort of "signature," you'll probably want to turn this feature on.
  If, on the other hand, most of your users only fill out those fields
  with information relevant to a specific post, you'll want to keep
  it turned off.

$AllowUserPrefs:  If you set this variable to 0, users will *not* be
  able to alter the style in which messages are displayed.  (They will,
  of course, still be able to search for specific messages.)

$AllowNewThreads:  If you set this variable to 0, users will be able to
  post responses to messages, but will *not* be able to start new
  threads.  (See also $AllowResponses, below.)

$AllowResponses:  If you set this variable to 0, users will only be able
  to post new messages; posting follow-ups (responses) to existing
  messages will not be possible.  This is useful if, for example, you're
  setting up a "classified ads" system, and don't want visitors to be
  able to respond publicly to the listings.  Note that if you set both
  $AllowNewThreads and $AllowResponses to 0, users will not be able to
  post any messages at all.  This is very similar to the result you get
  if you define $ArchiveOnly as 1.  However, there is one important
  difference.  A true archive board will not allow users to specify
  a time frame to view, since, for example, viewing all messages posted
  within the last "2 Week(s)" is rather pointless if the board doesn't
  contain any messages posted less then two months ago.  On these
  boards, only actual searches (which can, of course, include date
  ranges) will display any messages.  On the other hand, if you have
  *not* defined the board as an archive board, but have simply "turned
  off" both $AllowNewThreads and $AllowResponses, users *will* be able
  to select default time frames for their viewing.  If you're running
  a *busy* "announcements" board, this is probably a preferable option.

$NaughtyWordsFile:  You can, if you like, define here the path of a file
  in which "naughty" language (words or phrases you don't want included
  in posts on your forum) will be stored.  The file can be edited with
  the administrative script.

$CensorPosts:  If this variable is set to 1, any words (or character
  strings) matching the contents of the "naughty words" file will be
  replaced by a string of hash marks in the actual post.  For example,
  if you defined $NaughtyWords 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."  If you
  leave this variable set to 0, a message containing forbidden words
  will not be posted at all; instead, the poster will be shown a message
  stating that his message was rejected for content, and will be given
  the option to go back and "clean up" the post himself.

$ShowPosterIP:  If you set this variable to 1, whenever a visitor posts
  a message, the "thanks for posting" message will display his IP address
  and host domain.  This can serve as a subtle reminder to potential
  troublemakers that they aren't really anonymous, but is *not* likely
  to annoy legitimate posters and visitors, as displaying IP addresses on
  the index page might.

$BannedIPs:  You can, if you like, define here the path of a file in
  which the IP addresses or domain names of any individuals you want
  banned from your forum will be stored.  The file can be edited with
  the administrative script.

$BanLevel:  If this variable is set to 0, anyone whose IP address or
  domain name matches an entry in the "banned users" file will simply
  be unable to post messages to your forum.  If it is set to 1, such
  visitors *will* be able to submit posts, but those posts will only
  appear on the forum if and when an administrator approves them.  (In
  other words, they'll be treated as if you were running a moderated
  forum.)  If the $BanLevel variable is set to 2, on the other hand,
  such visitors will not only be unable to post, but will not even be
  able to read messages posted by others.  They won't have any access
  to the forum whatsoever.

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

CONVERTING OLDER WEBBBS IMPLEMENTATIONS

The 4.XX versions of WebBBS utilize a number of features -- the DBM
database file, the search index file, etc. -- which didn't exist in
earlier versions of the script.  As well, the organization of the data
files is different, as message files are now stored in a series of
subdirectories rather than in one single directory.

Upgrading is basically just a simple matter of replacing the old script
files with the new ones; however, there is, of course, a caveat.  Until
you tell the script to "rebuild" the database -- a process which not
only includes creation of the basic index database, but which also
includes creation of the search terms index and any necessary shuffling
of message files to new directories -- the new version of the script
won't know that your old messages exist.

There are two ways to rebuild (or, if this is a first time conversion,
to build) the necessary database files.  If your forum is relatively
small, you can simply access WebBBS directly from your browser, with
"?rebuild" tacked on to the end of the URL.  (For example, you could
call "http://www.foo.com/forum/index.cgi?rebuild" to force a needed
build or rebuild.)

But if your forum is fairly busy, WebBBS might not be able to handle the
entire conversion process in the time your browser is willing to wait.
(In particular, construction of the search index file can take a while,
since each message file has to be opened and read.)  If you have more
than a few hundred messages on your forum to be converted, you need to do
one of two things.  Either run the new WebBBS script the first time from
your telnet command prompt, rather than through your browser, including
"rebuild" as a command line argument (as in "./index.cgi rebuild") or
convert only a few hundred messages at a time.  (In other words, move a
few hundred messages into your data directory, run the rebuild from your
browser, then move a few hundred more into your data directory, run
another rebuild, etc.)  Obviously, the former is more efficient, but if
you don't have telnet access, and don't want to move to a better hosting
service, the latter may be your only option.

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

CHANGING DBM (DATABASE) MODULES

WebBBS uses DBM databases.  There are a variety of DBM "modules"
available, at least one of which should be available on any server on
which Perl has been installed.  As you'd expect, though, not all
modules are created equal.

WebBBS utilizes by default the "AnyDBM_File" DBM module.  In most
cases, this will not need to be changed; on most servers, the "default"
DBM module selected when "AnyDBM_File" is referenced will be the most
efficient one available.  However, if you notice your forum running
very slowly, and/or notice that your DBM file(s) are incredibly large
(hundreds of meg or more in size), you may want to contact your system
administrators and find out what other modules are available to you
or can be installed for you.  You can reference a particular desired
module simply by uncommenting the following line in the configuration
file:

BEGIN { @AnyDBM_File:ISA = qw (DB_File) }

And if necessary replacing "DB_File" with the name of the actual module
you wish to use.  (The DB_File module, by the way, if it's available to
you, is probably the one you want to use.  It seems to be the fastest
and most efficient of all the available choices.)

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

DISPLAYING "QUICK INFO" ABOUT YOUR FORUM(S) ON OTHER PAGES

You can display "quick info" -- the date of the newest message and, if
cookies are being utilized, the number of new messages -- on other pages
by calling the WebBBS script from an SSI tag.

On most systems, a tag such as the following should work:

  <!--#exec cgi="/webbbs/config.pl"-->

Some systems, though, don't set the DOCUMENT_URI environment variable
that WebBBS uses to tell whether it was called from an SSI tag.  Most
of those systems, though, also don't recognize the fact that SSI tags
aren't supposed to be able to include QUERY_STRING data, so if you find
the above tag trying to load the entire WebBBS index page, you'll most
likely find that the following tag will work instead:

  <!--#exec cgi="/webbbs/config.pl?quickinfo"-->

You can also create static links, if you like, directly to the most
recently-posted message on each of your forums.  Simply link to
"config.pl?review=0" instead of directly to "config.pl"; when followed,
the link will take you or your visitor directly to the forum's newest
message.

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

E-MAIL NOTIFICATION LISTS

Although WebBBS can handle fairly large e-mail notification lists,
you'll probably find as your board gets busier that your subscribers
don't like getting lots and lots of individual message notifications.
If you're running a board with heavy traffic, you should probably
switch from the basic "as messages are posted" notification scheme to
the more efficient digest setup.  (As noted above, the digest mailings
are *not* sent out by WebBBS itself; they are handled through the
separate digest script, available from the WebScripts site, which can
easily be set via cron to run automatically at regularly-scheduled
intervals.)

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

WEBBBS SECURITY

Though WebBBS does not yet directly incorporate password protection, it
works quite well with server-based protection.  All you need to do is
locate your configuration file in a password-protected directory.  And
if your security system sets the "REMOTE_USER" environment variable, as
most do, you can even set WebBBS to require that users post under their
login IDs, thus preventing them from posting under someone else's name.

Even if you're not password-protecting your BBS, you should still either
password-protect your data directory, or locate it outside of your Web
space.  There's no need for the directory itself to be accessible to the
public, and you're probably better off if it isn't.  (NOTE that the
directory *does* need to be set world-writable, as stated above; what I
mean here is that it doesn't need to be physically located within your
Web space.  The script needs to be able to read its contents, but your
visitors don't!)

If you want to set up a board which anyone can read but to which only a
few designated people may post, you can easily do so by setting up two
configuration files for the same data directory.  One would be publicly
accessible, but defined as "read only"; the other would allow posting,
but be accessible only to those with appropriate IDs and passwords.

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

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 in the "insertadvert" subroutine at the end
of the WebBBS configuration file to point to your ads.pl (WebAdverts
display configuration) script.

Once that is done, you can include banners anywhere in your header or
footer files simply by inserting the comment line "<!--InsertAdvert-->"
wherever you want a banner to appear.  (THIS CODE MUST BE ON A LINE BY
ITSELF!)

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

REGISTERING WEBBBS:

WebBBS is shareware.  If you use it, please register it!  The
registration fee is only $50 (US).  Payment should be sent via check or
money order to Darryl C. Burgdorf, Affordable Web Space Design, 3524
Pacific Street, Omaha NE 68105.

(If you happen to live in a country other than the United States, you
can write a check in your local currency for the equivalent of $57.50.
That will cover the $50 registration fee and the $7.50 service fee which
my bank charges.  Please do *not* write me a check in US funds drawn on
a non-US bank; the service charge for those can be anywhere from $10 to
$25!)

The unregistered version of the script is not crippled in any way.  I'm
not trying to "coerce" anyone into sending me money.  But I don't think
it's an unreasonable request.  I believe WebBBS is a commercial-
quality product; a *lot* of work has gone into its creation.  If you
use it, I'd appreciate it if you would be kind enough to send in the
registration fee.  I'll be that much more likely to be able to continue
spending time and effort on the scripts in the WebScripts collection,
and you'll have the satisfaction of knowing you did the right thing.  ;)

As well, as a registered user of the script, you'll be able to download
and utilize the WebBBS administrative maintenance script, which, while
not strictly *necessary*, will probably make your life easier.  It allows
you to easily delete, edit or archive messages, and also allows messages
to be "re-parented" if you believe they were posted in follow-up to the
wrong post.  And, of course, the admin script is necessary if you wish
to run a moderated board.

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

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
