 Something important to know about YAK
 =====================================

Examples of this file are for Linux version, but you should get the idea of
them even if you haven't used Linux.

This file has following sections:

0. Errorlevels
1. Command line parameters
2. Files YAK creates
3. Filebase
4. CD support
5. Doors
6. Graph files
7. Menu files
8. FAQ


0. Errorlevels
--------------

 0  - No error
 1  - Error reading configuration/data files
 90 - Quit requested in "Waiting for call" screen
 91 - Couldn't initialize modem

1. Command line parameters
--------------------------

 node       - Set node status <param 3> for node <param 2>. <param 3> can be
              one of the following:
                   0  - DOWN
                   1  - Doing nothing
                   2  - Browsing filelist
                   3  - Reading messages
                   4  - Writing message
                   5  - Downloading
                   6  - Uploading
                   7  - Playing door
                   8  - Logging in
                   9  - Chatting with sysop
                   10 - Checking new files
                   11 - Searching files
                   12 - Grabbing messages
                   13 - Waiting for caller
 packuser   - Pack userbase
 useridx    - Create userbase.idx file if it gets corrupted
 buildfb    - Build filebase. Usage: bbs buildfb [filebase name]
              [path to start reading] [<first subarea> <first jumparea>]
              See "Filebase" and "CD support" sections for more information.
 joinfb     - Join one filebase to another. Usage:bbs joinfb <original
              filebase> <filebase to join, ...>. See "CD support" section for
              more information.
 getdescs   - Describe files - scan each directory and add every file found
              into descript.ion. If file wasn't found from descript.ion or it
              was described as <No description>, try to get description from
              file_id.diz inside packet and if not found, check if there's
              files.bbs in that directory which has its description.


 -h:<h>     - Open port with handle <h> - DOS and OS/2 versions should use this
              parameter. With DOS version this should be the number of the COM
              port to use. With OS/2 this should be the COM port handle to
              use.
 -c:<port>  - Put COM port <port> in dorinfo?.def file for doors. Does nothing
              in DOS version.
 -p:<dev>   - Open device <dev> - Linux version should use this. This should be
              /dev/cua1 or something ..
 -b:<bps>   - Current connection BPS rate (default = 0)
 -t:<tty#>  - [Linux] Redirect stdout to /dev/tty<#>
 -n:<node>  - Put user to node <node> (default = 1)
 -l         - This is a local login
 -w         - Run in "Wait for caller" mode
 -u <uname> - Log in with user name <uname> 


2. Files YAK creates
------------------------

To data path (/usr/local/lib/yak) :

 bbsusage.dat - BBS usage data file, used by USAGE command
 dupemsgs.dat - Dupe message data file
 lastcall.dat - Last callers data file
 msgid.dat    - For proper MSGID creating with multinode systems
 userbase.idx - User index file, if this gets corrupted, use "bbs useridx"
                command to create new from userbase.dat
 userbase.dat - User data file, this tends to grow big easily, use
                "bbs packuser" command to remove old fields (users can be in
                BBS while packing userbase without any data loss).
 filebase.idx - Filebase index file - see "Filebase" section
 filebase.dat - Filebase data file - see "Filebase" section

To common path (/tmp) :

 dorinfo?.def - File for door games.
 nodemsg.*    - Node message files for each node
 nodes.bbs    - Users who are logged in currently
 ack.*        - Messages from dosemu in Linux version - see "Doors" section
 buildfb.sem  - Filebase building semaphore - see "Filebase" section


3. Filebase
-----------

YAK needs filebase files to use search commands. This should be build every
time new files are uploaded to BBS or existing files are deleted or moved to
different directory. YAK creates /common_path/buildfb.sem file every time
new file is uploaded into BBS. Linux version runs /usr/local/bin/buildfb.sh if
buildfb.sem exists before it quits. For OS/2 and DOS versions you should
create a .bat or .cmd file something like:

:start
del \common\quitbbs.%1
bbs -w -p -n:%1
if errorlevel==90 echo > \common\quitbbs.%1
if exist \common\buildfb.sem goto buildfb
if exist \common\quitbbs.%1 quit
goto start

:buildfb
bbs buildfb
if exist \common\quitbbs.%1 quit
goto start

4. CD support
-------------

To make YAK to read CDs, you have to first build a filebase of it,
join your filebase with cdrom's filebase file and add every directory of CD to
fareas.bbs. CD's filebase should be quite easy to build:

bbs buildfb cdrom /cdrom

Buildfb can read descript.ion, files.bbs and INDEX files to get descriptions
of files. If it founds one, it indexes only files listed in that file. If it
doesn't, it adds every file in that directory to filebase without description
[STILL UNDER CONSTRUCTION].

Then you have to join cdrom filebase to YAK's filebase:

bbs joinfb filebase cdrom   # cdrom2 cdrom3 etc...

Finally you need to add every directory in CD to fareas.bbs. And to make this
easier, buildfb can do it itself with few extra parameters:

bbs buildfb cdrom /cdrom 2 100

2 means that cdrom-directory is to be displayed in sub directory 2 (normally
root directory) and 100 is the number of the first "next area" field to use
(see fareas.bbs to details how subareas work).


5. Doors
--------

Doors should run quite easily with DOS and OS/2 versions (use q_exec menutype),
but what about Linux? Is there any way to use DOS doors under Linux? Sure, just
get DOS emulator and do a little fix in it so it doesn't drop carrier when it's
started:

(v0.66.0)
file src/base/serial/ser_init.c:
function do_ser_init():
last lines:

  /* Pull down DTR and RTS.  This is the most natural for most comm */
  /* devices including mice so that DTR rises during mouse init.    */
  data = TIOCM_DTR | TIOCM_RTS;
  ioctl(com[num].fd, TIOCMBIC, &data);

Just comment out these lines and compile. Remember to add 'serial' lines to
dosemu's configuration file, each node must have its own configuration file
/etc/dosemu<node number>.conf.

OK, now DOS emulator works. Then we have to tell it to start doors, so add this
batch file to autoexec.bat:

 == waiting.btm ==
if not "%1" == "" goto loop
echo Give node number as parameter!
quit

:start
*del d:\tmp\waiting.%1

:loop

if exist d:\tmp\waiting.%1 goto check_wait

delay 1

goto loop

:check_wait
set handle=%@FILEOPEN[d:\tmp\waiting.%1,read]
if %handle% eq -1 goto start
set chr=%@FILEREAD[%handle%,1]

rem -------- Check first character from waiting.%1 :
if %chr% eq * goto run_lore
if %chr% eq L goto run_lord
if %chr% eq G goto run_war
if %chr% eq Q goto quit
goto start

:run_lord
>d:\tmp\ack.%1
cdd d:\doors\lord
call run %1
cdd d:\doors
set handle=%@FILECLOSE[%handle%]
goto start

:run_lore
>d:\tmp\ack.%1
cdd d:\doors\lore
call lore /N%1 /Pd:\tmp
cdd d:\doors
set handle=%@FILECLOSE[%handle%]
goto start

:run_war
>d:\tmp\ack.%1
cdd d:\doors\gwar
call war.btm %1
cdd d:\doors
set handle=%@FILECLOSE[%handle%]
goto start

:quit
unset handle
unset chr
*del d:\tmp\waiting.%1
 == waiting.btm ==

If you don't want to use 4dos, you have to do a program which does same as
batch abowe.. That should be about all to make DOS doors to work under Linux..


6. Graph files
--------------

All graphics SkyReader displays are in *.ans files even though they're not any
ANSI files .. Colors are changed with @X<bg><fg> macro where fg and bg are
background and foreground colors in hex, like @X0F = white on black. Here's all
the colors:

  0 = Black     8 = Dark grey
  1 = Blue      9 = Bright blue
  2 = Green     A = Bright green
  3 = Cyan      B = Bright cyan
  4 = Red       C = Bright red
  5 = Magneta   D = Bright magneta
  6 = Brown     E = Yellow
  7 = Grey      F = White

There's also some other special macros:

@CLR@         - Clears screen
@CLREOL@      - Clears to end of line
@GOTO:x,y@    - Move cursor to x,y on screen
@BAR:pos,max@ - Display a nice "bar" :) which has length pos of maximum max
@MON@         - More-prompt on - start checking when "More (Y/n)" should be
                asked.
@MOFF@        - More-prompt off
@SCOL@        - Save current color
@RCOL@        - Restore saved color

Only with ANSI X3.64 emulation:

@SCROLL_DOWN:y@ - Scroll rest of screen one line down starting from line y
@SCROLL_UP:y@   - Same as above, but scroll screen up
@INSCHR@        - Insert character to current cursor position
@DELCHR@        - Remove character from current cursor position
@INSLINE@       - Insert line to current cursor position
@DELLINE@       - Remove line from current cursor position

And then there are some normal macros which can be found from file MACROS.


7. Menu files
-------------

All commands YAK recognizes are in *.mnu files. Here's a usual top menu
file with few explanations:

; All menutype names are defined in defines.mnu, there's complete list of all
; commands what YAK can use. You could also use command numbers directly
; instead of their names, but I don't recommend it because command names won't
; change as easily as their numbers..
ifndef DEFINES_MNU
  include "defines.mnu"
endif

; Auto execute lines - these lines are executed every time this menu file is
; read:

; cmd   menutype    data
; ---   --------    -----------------------------------------------------------
; Usually you want a prompt, so display it first:
  auto  q_print     "@CR@@X0Fenter your command: @X07"
; Then you probably want to ask user what (s)he would like to do - without this
; (or similiar) command YAK just loops this file forever!!
  auto  q_askstr    "80"

; Commands that work only in this menu

; cmd   key     menutype    data
; ---   ---     --------    ---------------------------------------------------
  cmd   ?       q_showansi  "top.ans"
  cmd   sh      q_userlist

; All generic commands which work in every menu are defined in include.mnu:
include "include.mnu"

Hope this helped at least little. :)

8. FAQ
------

Q: Is there any user editor? I can't delete any users!
A: Use "user" command in setup menu to change to user which you want to edit.
   Use "kill" command to delete/undelete user.

Q: How do I make YAK to answer calls under Linux?
A: Best way is to use mgetty (or any getty-clone), only disadvantage is that
   YAK can't see connect string so it can't know which BPS user is logged in ..
   This could be fixed quite easily with modifying mgetty's sources though.
   Anyway, install mgetty, create user "bbs" and modify /etc/passwd so that
   command shell is "/usr/local/bin/bbs -h:0".

   Another way is to use YAK's -w switch to wait wor calls (doesn't work right
   yet..)

Q: [Linux] I want to see what my users are doing!
A: If you use mgetty to answer to calls, add -t:<ttynum> parameter to
   /etc/passwd to send output to /dev/tty<ttynum>. If you have multiple lines,
   you should use a "runbbs" program, I use src/runbbs.c .. Though YAK should
   check internally these settings from yak.conf... I'll do it some day. :)
