The aD! Project!
aD! BBS v. 3.0 (c) 1995, 1996, 1997, 1998 Chris Church
bbs-lib v. 0.61 (c) 1995, 1996, 1997, 1998 Chris Church
fsearch.ph v.1.15 (c) 1995, 1996, 1997, 1998 Chris Church
	  All modules contain their version info

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
 3.d - menu tops
4 - RTPI
5 - File Bases
6 - Group Permissions
7 - Modular Format
8 - ISR Menu Command Completion and Input Methods
9 - About Colours & Strings
10 - What's New?
11 - Known Bugs
12 - 'Todo' List
13 - Notes / Thanks / Contacting
----------------------------------------------------------------------

 
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
one of my strong points.   


2. System Requirements

	UNIX, or a clone (Linux works nicely, as does Solaris)
	PERL 5.001 or better
	ReadKey perl module (included)
	(May port to OS2/Win95/WinNT)

3. Setting things up

3.a : Installing
	
  Step 1:
	 Create a directory for the modules (e.g. /usr/local/etc/ad_mods)
	 Place all files in the libs/mods/ dir here.
	 Place all files in the libs/ directory in your perl directory.
	 (note: perl directory is usually /usr/lib/perl5 or
	  /usr/local/lib/perl5)
 
  Step 2: 
	 Run Make_Config, it will ask you some simple questions about how
	 you would like to setup your BBS.  It will create a file in /tmp
	 named 'adbbs.cf.mk'.  Note: to make it easier on yourself, to run
	 Make_Config, type 'perl ./Make_Config'.  You will still need to
	 manually edit the adbbs.cf to customize your BBS fully. 
	 Make_Config just gives you enoguh to get started.

  Step 3:
	 Copy /tmp/adbbs.cf.mk to /usr/local/etc/adbbs.cf.
	 Edit confs/strings.ph to your liking (see colours & strings below)
	 Copy confs/strings.ph /usr/local/etc/strings.ph.

  Step 4: 
	 Compile and setup ReadKey if you have not already.
	 Note: you do not need this if you do plan to use the
	 'ansi-support' option. (see 3.b about adbbs.cf)

  Step 4:
	 If your perl binary resides in a directory other than
	 /usr/local/bin, you will need to either edit the first line of the
         adbbs script to reflect the real path, or make a symlink to 
	 /usr/local/bin/perl.
	 E.g.:
	 your perl bin = /usr/bin/perl
	 the first line of adbbs should read:
	 #!/usr/bin/perl
	 or, make a symlink:
	 ln -s /usr/bin/perl /usr/local/bin/perl	 	 


	Upgrading:
		  The status of the .aDrc's have not changed, so your
		  users will not be broken, you will however need to 
		  go through all steps listed above to upgrade to version 
		  3.0.  Many changes have been made.
	

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.  Instead of
editing it by hand, you may (AND SHOULD!) run Make_Config!

Files :

$AMDIR = "/usr/local/lib/perl5/ad_mods";
    $AMDIR is the location of all modules for the BBS
    (see Installing and Modular Format)

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

$RNDIR = '/usr/local/etc/mtop';
	$RNDIR is the directory to store random mtop files.

Used only by fsearch.ph :

$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

Variables :

$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

$kbsec = 60;
	$kbsec is the number of seconds until timeout if using $u_ktime

Boolean Variables :
	a value 1 represents 'true', 0 'false'.

$showwel = 1;
	showwel, show welcome file(s) to user?
$shownews = 1;
	shownew, show system news file(s) to user?
$showmail = 1;
	showmail, show the amount of messages that are in the inbox  
	(use this if the mailcheck option does not work on your machine)

$u_singk = 1;
	u_singk, Use single-key entry for prompting, requires Term/ReadKey

$u_ktime = 1;
	u_ktime, Time out user input, exit if time out
 
$skwel = 1;
	skwel, Show skip welcome screens prompt

$sllogin = 1;
	sllogin, Show last login time & date

$ansi = 1;
	ansi, allow ansi support for colours & strings

$uisr = 0;
	uisr, use ISR command completion (see Command Completion)

$shfsize = 1;
	shfsize, show file size / info in file bases

$rndmtp = 0;
	rndmtp, randomize menu tops

$shmmsg = 1;
	shmmsg, goes with $rndmtp, show menu name at top of message?

$ugroup = 0;
	ugroup, use group security? (see Group Permissions)

$ufil = 1;
	ufil, use file base routines (see File Bases)
paths  : 

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


$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 or word>

 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		Calendar of Events
 prog		rtpi /bin/bbs/cal.pi
 mkey		Calendar

 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		mail

 the mail menu config file would be mail.cf

 look at the included main.cf for more examples.

 placing a "group	<group>" line will enable group support, see section
 6 about this.

3.d : menu tops

 Menu tops are displayed above the actual menu display, and below menu name

 As of 3.0 you have a few options for menu tops :

	A) display one (1) static menu top for all menus
	B) display a specified menu top for a specified menu
	C) choose randomly from a directory of menu tops

	You may also disable the display of the menu name (in strings.ph)

  A) To display one single, static menu top, simply point the variable
     $MTOP in adbbs.cf to your mtop file, and set $rndmtp to 0.  This will
     disable random menu tops. (note: you must set $rndmtp to 0!)

  B) Create a file in your menu directory (see menu.cf section) named 
     mtop.<menu>, where <menu> is the name of the menu that this menu top
     goes on. Set $rndmtp to 0.
  
  C) Set the variable $RNDIR (see adbbs.cf section) to the directory in
     which your mtop files are stored.  Also set the variable $rndmtp to 1.
     Files will randomly be chosen out of $RNDIR and displayed as menu tops.

	To disable display of the menu name, set $shmmsg (see adbbs.cf
	section) to 0.
		

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


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

 NOTE: if a file named 'files.bbs' is found in the directory, it will be
 used instead of the 'dir' display.  Colour codes may be used in the
 files.bbs.  A skeleton program has been provided to easily create
 files.bbs's in the ext/ directory.

 As of 3.0 you can now show user name and other information about the
 file when doing a show command (rather than the old text/binary & size)
 this can be overridden if the sysadmin changes the permissions of uploaded
 files, see the variable $shfsize in adbbs.cf.

6.  Group Permissions
	
	You may (as of 2.1a) specify which group may view a menu.  It's
really pretty simple to do this, first set $ugroup to 1 and then add a line
to your your <menu>.cf (preferrably at the top) like the following :

group		103

Then, only users which are members of the group with the GID 103 may view
this menu.  You may also use group 'names' instead of the GID.  To add a
user to a group, simply do either of the following:

	1) edit /etc/group
		This file contains groups, GID's, group names, group
passwords and group members.  You may add a user to a group by tacking them 
onto the end of an existing entry with a comma, e.g.: to add user 'billy' to
group 100 (public on my machine) i would make the following change in
/etc/group :

public::100:games,psylark

let's add 'billy' :

public::100:games,psylark,billy

Easy enough, eh? 

	2) make the group -their- group
		Just change their gid to the gid of the group you want them
to be in, either with chfn(1) or manually by editing the gid field in the
password file.



7.  Modular Format

	As of 3.0, a new 'modular' format of loading has been created to
  save memory overhead during run-time.  How it works is simple: 
	      If You Don't Need It - Don't Load It 
  Dummy routines replace core BBS routines that need to do little or
  nothing.  All 'mod' files are loaded ia the RTPI engine.
  Routines and variables involving options that are turned off are simply
  not loaded, resulting in cleaner and quicker start-up speeds.
  These are not your classic perl style modules.


8.  ISR Command Completion and Input Options

   You have a few options for your users' input:

	A) ISR Command Completion ($uisr)
	B) Single-Key Entry ($u_singk)
	C) Key+CR Entry
	D) Word+CR Entry

	A -  The ISR Command Completion Engine, a new feature as of 3.0, 
	     allows users to enter commands by only typing in a unique 
	     string to a command.  i.e.:
		Command options are (a,b,c,d,e) :
		user enters 'a'
		Before CR is hit, the BBS finds that no other command
		key (or string) contains the letter 'a' and automatically
		runs command associated with the key.

		This differs from Single-Key entry when combined with
		another new option in 3.0, word key commands.  For example,
		the following commands are available to the user:
		mail,internet,news,exit
		if the user types 'm', 'ai' or 'l', the command associated
		with the mail word key.  'net', 'in', 'nt', or 'te' will
		run that associated with internet, and so on.

	B -  This is useful in single-key key commands.  The user simply
	     hits the key associated and the action automatically ensues.

	C - Key+CR is the default method of entry, user hit single-key word
	   associated with action, hits CR and action is taken.

	D - New in 3.0 you can now (safely) use word keys, instead of
	    single keys associated with actions, you may now associate whole
	    words - without using the ISR Command Completion, the whole word
	    must be typed and CR hit to run associated command.	 
	
 See menu.cf section for info about associating keys and words.
 Setting both $uisr and $u_singk to 1 may result in unexpected behaviour.
 See adbbs.cf section about modifying these variables.

9.  About Colours 
	
 Almost all strings used by aD!BBS and almost all files read and displayed
 by aD!BBS use colour & string codes.  Strings may be found in
 confs/strings.ph.  In this file each string is listed as a regular perl 
 variable, e.g.:

	$stvar = "stuff";

 In each string (including text files displayed by bbs) command codes may be
 used, they go as follows:
 
	%d or %%dd
	d = 0-9, dd = 10-13.  d and dd are colour codes, change foreground
	colour this d or dd (you must use two (2) %'s for dual-digit colours)
	
	%%42
	center remaining text on screen - note, no command codes may be
	used after this command, effective until newline

	%%{ <code> }
	execute <code> and display result (if any) in string.
        this code is eval'd as part of the bbs (in the same way as rtpi)

	Some strings may include variables (see cofns/strings.ph)
	To include them, use the following format:
	+\$variable 

	(you must use the \ if you use double quotes, or leave it out if you 
	use single quotes)

	e.g.:
	$stfup = "Uploading +\$file\n");
	$eprom = '[menu: +$menu] hit enter';

  All command codes are disabled on files ending in .ans (ansi files) that
  are displayed.
 
10.  What's new ?

  Ver    Change
  ---    ------

  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.

  2.1a -
	All 'letter' versions from now on will just be 'upgrades'
	Added in option to show last login time & date
	Added in option to turn off prompting for welcome screens
	Added in simple new message scanning program to go along
	with the message bases.
	Added the Make_Config program to create the configuration files.
	Added in group permissions, see section 6 about implementing this.
	Began work on the hacker's guide to aD!BBS, currently does a brief
	overview of all the sub-routines used by the BBS, will go into
	greater detail in the future.

  2.1b -
	Fixed a bug with the find routine in the file engine
	Added file names to the find routine
 
  2.2  -
	Added in support to the file engine for files.bbs type listings
	Most strings now are stored externally in a files called strings.ph
	all strings accept colour codes now
	one may use multiple digit colour codes now [see about colours]
	created simple program labelled 'make_files.bbs"

  3.0 	-
	Added in menu command completion
	Added user name / info to show file info screen
	Made prewelcome screen external 	
	Random menu tops can now be used
	MTOP.menu can now be used
	(yet another) rsp display bug fixed
	Module-type loading system to lower memory usage
	Added in support for in-line commands inside of strings
	Added in centering for strings


11.  Known Bugs

	None at this time

12.  Todo List

	As if you had to ask - it's a mile long I've been behind for over a 
	year.

13.  Notes / Thanks / Contacting

If you are upgrading to 3.0 from any version,  you MUST go through a full
install.

Hopefully nothing big was missed in the packaging of this version, it's now
5:56 AM my time, and everything _seems_ to be OK =)

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

I can use beta testers!  The reason bugs stay in the code so long before
getting fixed is a lack of people letting me know what's going on..  I can't
test every possible condition, so if you want to help out (means you get the
code before I put it on the site, and that you have an open ear over
here for any changes) email psylark@netropolis.net.

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

http://www.netropolis.net/aD/ ||
ftp://sunsite.unc.edu/pub/Linux/system/BBS/bbs/

If you add on anything to it, please email me at any of the following
addresses: psylark@netropolis.net
Snail Mail:

	The aD! Project
	9532 Windswept
	Houston, TX 77063

Read the file COPYING for information about copying, distribution, etc.
			       1/12/98