aD! BBS v. 2.1 (c) 1995, 1996 aD! Data Systems / Chris Church
bbs-lib v. 0.60 (c) 1995, 1996 aD! Data Systems / Chris Church
ansi.ph (c) 1995 Micro^[[, 1996 aD! Data Systems / Chris Church
fbase.ph v. 0.35 (c) 1995, 1996 aD! Data Systems / Chris Church
psylark@aD.org 

1 - About The Program
2 - System requirements
3 - Installing & Setting Things Up (The Configuration Files)
 3.a - installing
 3.b - adbbs.cf
 3.c - menu.cf
4 - RTPI
5 - file bases
6 - Known Bugs
7 - Todo List
8 - About Colours
9 - What's New?
10 - Notes / Thanks
----------------------------------------------------------------------

 
1. About The Program

	aD! BBS was basically written to provide a nice, easy to use menu /
bbs interface, currently it doesn't handle special permissions, group
permissions, etc. but they are in the 'todo' list. =)  One day, I was
working on the C code for my bbs (I'm not the greatest C coder out there,
not even a good one =) and wondered if anyone had written one in Perl.  I
looked around on ftp sites, and couldn't find one.  Well, I decided to write
one myself.  It reads from menu configuration files, for what to
display, do, etc.  Can override global settings with individual user
settings. It also has a main configuration file, that sets a few
global variables and the ability to read perl code on the fly and treat it
as part of the bbs. Make SURE to read ALL of this file, I'm sorry it's so
sparse in areas, and obfuscated in others but, documentation has never been
on of my strong points. =)  


2. System Requirements

	UNIX, or a clone (preferrably linux, as that's all I've tested it on)
	PERL 5.001 or better (upgrade || die();)
	May work on a OS2/NT platform, I may test that later.
	ReadKey perl module (included)

3. Setting things up

3.a : Installing
	Copy all of the files in the libs/ dir into your @INC path (usually
/usr/local/lib/perl5 or /usr/lib/perl5) and then copy confs/adbbs.cf to
/usr/local/etc.  Then edit it to your needs.  You will need to define a
a few directories.  You will also need to setup & compile readkey if you do
not already have it installed.  Note, if your perl executable is something
other than /usr/local/bin/perl, you will need to change the first line of
adbbs to reflect the real path, or make a link to your perl binary in
/usr/local/bin.

3.b : adbbs.cf (/usr/local/etc/adbbs.cf)
	This is the main configuration file for the bbs/menu system, I have
to admit that I cheated on it, it's in regular perl format.

$eprom = "Hit <ENTER> to continue";
 
 $eprom is the 'Hit enter' prompt, just make it whatever you want

$cprom = "aD! Enter Choice ->"; 
 
 $cprom is the 'Choice' prompt, again, make it what you like.


$WDIR = "/usr/local/etc/welcome";
  
    $wdir is where the welcome files rest, in the form welcome.1, welcome.2,
    etc.

$NDIR = "/usr/local/etc/news";
 
    $ndir is where the news files rest, just like the welcome files


$MDIR = "/usr/local/etc/menu";

    $mdir is where the menu configuration files rest, in the form menu.cf
    main.cf -must- exist, and will be the first menu
    the mail menu should / had better be mail.cf =)

$MTOP = "/usr/local/etc/menu/mtop";

    $mtop is the file that is displayed at the top of the menus


$GBFILE = "/usr/local/etc/goodbye.msg";

	$gbfile is the file shown when the user exits

$FDIR = '/usr/multi/ftp/pub';

	$FDIR is the directory in which the users may view / download files

$IDIR = '/usr/multi/ftp/incoming';
	
	$IDIR is the directory in which the users may upload files.

$tppath = "/usr/bin/tput";

	the path to 'tput'. sorry, but for brevity of code, and
	sanity, i just used a system call instead of the termcap.pl 
	to handle clearing the screen.

$PASSWDF = "/etc/passwd";

	$passwdf is the passwd file, usually /etc/passwd

$CF = '/usr/local/etc/crunch.db';
	
	$CF is the file for the readme/index searchable database

$lib_file = '/usr/local/etc/fildb.db';

	$lib_file is the file used for the database of all files

$showwel = 1;
$shownews = 1;
$showmail = 1;

	these three are boolean values, 1 for yes, 0 for no.
	showwel is whether or not to show the welcome files
	shownews is same, except news
	showmail is whether or not to show the amount of messages that are
        in the inbox  (use this if the mailcheck option does not work on
        your machine)

$hostrt = "chao";

	$hostrt is the "short" name for your host

$hostend = "aD.org";

	$hostend is the domain you are in...  If you are not the MX for this
	domain, i'd suggest making this your FQDN (fully qualified domain name)	
	e.g.: chao.aD.org

## obsolete as of 2.1! ##
$u_pos = 0;

	$u_pos is boolean, 1 for true, 0 for false
	Use POSIX masking on external program execution
	(note - !! WILL ADD ALMOST 3 SECONDS TO PROGRAM STARTUP!!)
##			##

$u_singk = 1;

	$u_singk is boolean, 1 for true, 0 for false 
	Use single-key entry for prompting, requires Term/ReadKey

$u_ktime = 1;

	$u_ktime is boolean, 1 for true, 0 for false
	Time out user input, exit if time out

$kbsec = 60;

	$kbsec is the number of seconds until timeout if using $u_ktime
 
$sz
$sx
$rz
$rx
        
	These variables are for the file bases, they are the paths to the
respective programs, sz - rx... 

3.c : menu.cf
	The menu configuration files have a special format, which is :

option		<text>
action		action
mkey		<key>

the action can be either prog (for "program") or menu (to change menus)
a few special 'actions' can be used after prog, they are 'ed' to paginate a
file, 'goodbye' to logout, 'cprom' to conmfigure prompts, 'ttype' to set the
terminal type, 'rtpi' to invoke the rtpi loader, 'fbase' to enter the file 
bases e.g:

option		View the motd
prog		ed /etc/motd
mkey		V

option		Calender of Events
prog		rtpi /bin/bbs/cal.pi
mkey		C

When 'menu' is used, the action text is the menu to go to, and also the name
of the config file.

option		Mail Menu
menu		mail
mkey		M

the mail menu config file would be mail.cf

look at the included main.cf for more examples.


4.  RTPI - Run Time PERL Inclusion

	Now, as of 2.0 you can have your perl scripts run as part of the bbs
 without editing the actual bbs source code (it's easier this way, trust me =)
 

	With the rtpi prog keyword inside a menu.cf, you can load your perl
 scripts as part of the bbs.  Just write a perl script, which can use any
 bbs sub-routine or variable, and place it in the file pointed to by the
 rtpi line of your choice...


  e.g.:

	basic.cf - a basic menu configuration file

	option	blah
	prog	rtpi /usr/local/bin/hello.pi
	mkey	B

	hello.pi - a basic perl script

	&clear; # internal to the bbs!
	print("Hello World!\n"); # perl call
	&eprom; # bbs enter prompt


 REMEMBER : do not use return() outside of a loop in your program, and do
 NOT use exit().  Your code will not stay memory-resident, unless you define
 sub-routines.  Any variables / arrays / lists you do not undef() will also
 stay.

             new in 2.1:

 $MDIR/prerun.pi : if you have a file named "prerun.pi" in your menu dir, it
will be run before ANYTHING else in the bbs, immdiatly after loading, this
can be helpful for setting up dialup lines, timers, etc..
 $MDIR/menu.pi  : if you have a file called "main.pi" in your menu dir, then
main.pi will be run everytime before entering the main menu, i.e., if you
have mail.pi, it will be run before the mail menu is displayed.. etc..
 $MDIR/goodbye.pi : goodbye.pi is the last thing run by the bbs, just before
exiting, great for cleanign up temp files prerun.pi may have left, shutting
off timers, and cleaning up terminal devices.
  

    
5.  File Bases

	In the file bases, a few basic options are given:
	quit         - exit
	ls	     - list files	
	help	     - show help
	down         - downlaod a file from current dir
	put          - put a file
	view	     - view a (text) file
	show         - show information about a file
	cd           - change directories
	cdup (cd ..) - go to parent directory
	find <regexp>- find lines based on a reg. expression

 The users are not allowed to go higher in the directory tree than what is
 set in $FDIR, they will recieve the message "Already At Highest Directory"
 if they try...   to allow them to enter the file bases, add an option with
 "fbase" as the prog.

 the find command uses the fsearch.ph library, you must create a file as 
 pointed by $CF in the adbbs.cf, in the proper format, the easiest way to do
 this is to use the updatedb.pl provided in ext/, put it in crontab or some
 other such automation utility, and have it run once a day or so..


6.  Known Bugs

	None currently known

7.  Todo list
	
	Heh, always alot... for now : new message searching and tighter
posix code =)


8.  About Colours 
	
	aD! BBS (as of 1.5) Now supports ANSI Colours in prompts.  Use the
cprom prog option to do this, you may also set these in your configure
file...  in prompts, a color is specified with '%' i.e. : %5... valid
numbers are 0 (black) - 9 (white).

9.  What's new ?

  1.4  - made the code tighter, cleaner  and perl 5 dependant..
  1.5  - added in support for ansi colours tnx go to Micro^[[ for the C
	 ANSi.h i used.  Also added in terminal types, and the basic engine
	 for user settings storage.. (see cprom and ttype).
  1.6  - added in fbase.ph, with support for file bases now, and also
	 added in some traps for the unwary. 
  1.6a - removed a bug with fbase.ph that allowed users to go up past the
	'secure' directory.  Hoepfully too many people didn't grab 1.6 (1.6b
	was released about 6 hours after 1.6 =)
  1.6b - again fixed the bug in fbase.ph seems i overlooked one small point

  1.6c -
	- POSIX SIGINT and SIGQUIT masking on launch of external programs
	[configurable] [Uncle Bob]
	- Option to Use Single-Key entry rather than key+CR 
	[configurable] [Uncle Bob]
	- Place <menu>.scr in menus directory to display instead of default 
	display of menu.cf.
	[Uncle Bob]
	- Place <menu>.cf in user's home directory to override use of global cf file
	- The ability to time out a user after seconds of no input
	[Configurable] [Uncle Bob]
  2.0 - 
	Added in file list database support, as well as a searchable
	database of readme's / indeces
	Added in RTPI, see notes about RTPI
	fixed another bug in fbase.ph, in older versions you could override
	the $FDIR variable by typing "cd ./.." *sigh* i hate fixing the cd..
	bug =)
	Added in support for infinite loops inside the menus caused by line
	noise
	[Uncle Bob]

  2.1 -
	Cleaned up the RTPI loader, there is a bug with version 2.0 :
	RTPI loaded scripts will continue to be run time after time (i.e :
	they stack up..) which has been fixed in 2.1
	Added prerun.pi option, menu.pi option, and goodbye.pi option, see
	RTPI section above for details.
	Removed the POSIX code for the time being (sorry uncle Bob, but it
	took way too long to load on my dx2-66) Will add it back once I get
	around to making it smaller + dynamic.
	Created a (functional!) message base system, see ext/messages/README
	for details on setting up.
	Worked against bulk : removed obsolete stuff such as "uinfo"
	Fixed the rsp (really small pager) function to display correctly.

 10.  Notes / Thanks

 If you are upgrading from 1.3 to anything, you MUST replace your existing
adbbs.cf with the new one included in the package.. case sesnativity is true
=)

Many Thanks goto Uncle Bob (root@gobblernet.lod.com) of the Gobblernet BBS
for his help with the new things in this distribution, and his support for
this software!


NOTE: if you use the POSIX complaince, it will more than double your
starting load time (comes to about 5 seconds on my dx2/66) 

If you have any contributions, please send them to me =)

ftp://ftp.aD.org/pub/aD/adbbs/

If you add on anything to it, please email me at any of the following
addresses: psylark@ad.org, or chris@neosoft.com
Read the file COPYING for information about copying, disstribution, etc.
 

		
	
