This users manual is under construction and has not yet been completed

Introduction

kshEngine is a web based program which will automatically and dynamically
generate an entire web site. kshEngine will present an HTML view of
a hirarchical directory structure, subdirectories, files and hidden files.

The way the program works is that it reformats a directory list into a
single easy to navigate HTML page and inserts user defined information
into certain areas of each page. Each page is divided into a number of
sections which are:

Header information. Contains the web site title.

Link bar. Contains user defined URLs.

Search box

Category List. Contains a list of sub-directories in the current directory

Search Results. Only exists after performing a search.

Item list. Contains a list of files in the current directory.

Link bar. Same as above

Info bar. Contains information about who to contact regarding the web site.

The program first obtains a list of directories and files in the current
directory. It then displays the directories as "Categories" and each
file as an "Item". The starting directory is determined at installation
and defined by the web site administrator. During the installation
process, the web sited administrator is asked to define the top level
document directory for kshEngine. The default answer is "engine".
Using as an example "/home/httpd/html" as the full path document
directory, of the web server, the kshEngine top level document directory
would then be "/home/httpd/html/engine".

Installation

The installation process must be run as the "root" user or it will not
execute successfully. The reason for this is that the installation
process performs a change owner command on each file it installs.
Unless you are logged in as "root" this will fail and the installation
will not be successful.

Several pieces of information about your web server are required in order to
install kshEngine. The information required is:

Full directory path to the parent directory of the cgi-bin directory

For example, if your cgi-bin directory is
"/usr/local/etc/httpd/cgi-bin", then the answer to this question would
be "/usr/local/etc/httpd"

Directory name of your cgi-bin where you want to install kshEngine

This would be the name of your cgi-bin directory. Normally this would
just be "cgi-bin" but your system may be configured differently, or you
may just want to install it in a different location.

Full directory path to the parent directory of the HTML documents directory

For example, if your HTML documents directory is
"/usr/local/etc/httpd/htdocs", then the answer to this question would
be "/usr/local/etc/httpd"

Directory name of your HTML documents directory where you want to install kshEngine

This would be the name of your HTML documents directory. This varies
from web server to web server. It may be something like "docs" or
"htdocs" or "html", etc. You will need to determine this location before
beginning the installation process.

Directory name to use for kshEngine

This is the name of a directory which will be created under the cgi-bin
directory and the HTML documents directory. This directory will contain
the kshEngine programs and files. The default value is "engine".

Title to display on each page

This is a line of text which will be used as a title and displayed at
the top of each web page. The title should be only 1, 2 or 3 words.
The default title is "kshEngine".

User ID of the httpd process

This is the user ID of the owner of the web server program. The
installation program will change the ownership of the kshEngine
directories and files to this user ID. This is because the kshEngine directories
and files must be readable, writeable and executable by the owner of the
web server program.

Programs and Files

There are a number of user defined files which can exist in each
directory and can be used to control the look and feel of each page.
The files are:

.index - List of Items, URL's and descriptions of each

.titlebar - User defined title bar for each page (HTML)

.linkbar - User defined URL Link bar for each page (HTML)

.forinfo - Who to contact about this page (HTML)

.description - Description of the information containd in this page

Each of the above files can be defined by the user and can be different
for each and every page. Each directory and subdirectory may have any
or all of the above files. The ".titlebar", ".linkbar", and ".forinfo"
files should contain HTML code. The ".description" should contain a
paragraph of text which describes the current category. The ".index"
file contains Item information where each item is described per line,
and each line is separated into three fields.

FILE: .index

The ".index" file contains Item information in a flatfile database
format. The format of the file is one record per line with three fields
per record. The fields are:

Field 1: File name or Link text

Field 2: URL of the file or link

Field 3: Description of the file or link

The field separator is the pipe "|" character. Field 1 can be a file
name or link text of the item. Field 2 contains the URL to the file or
link. Field 3 contains a description of the item. A few examples
follow:

index.html||Link to a local file
index file|http://www.kshEngine.com/index.html|Link to a remote URL

The first line of item information above defines "index.html" as the
file name or link text. No URL information is defined and the
description is "Link to a local file". Since no URL is defined,
kshEngine will assume that "index.html" is a file in the current
directory and define a URL for that file pointing to the current
directory. kshEngine will generate an HTML link to the URL and
additionally display the description following the link.

The second line of item information defines "index file" as the link
text and the URL as "http://www.kshEngine.com/index.html". kshEngine
will generate an HTML link to the URL and additionally display the
description following the link.

kshEngine also automatically inserts new items into the ".index" file so
the user does not need to bother editing the ".index" file each time a
new file is added to a directory. kshEngine will automatically insert
the title information as the description field for HTML files and will
insert the first 64 characters of text files as the description field.

The default Header information is contained within a file called
"title.cgi". This is a Korn shell program which must be edited to suit
each individual web site. If a directory does not contain a ".titlebar"
file, then the page title will be the contents of "title.cgi".

FILE: .description

The ".description" file is a free form text file which can contain a
verbose description of the current web page. A ".description" file can
exist for each directory in the hirarchical structure and is displayed
automatically if it exists. The file can contain ascii text or HTML
code. If the file contains text, it will be displayed as a single
paragraph of information on the resultant web page. If the file
contains HTML code, it will be displayed according to the formatting
within the file.

FILE: .titlebar

The ".titlebar" file is a free form text file which can contain title
information for the current web page. A ".titlebar" file can exist for
each directory in the hirarchical structure and is displayed instead of
the default title information, if it exists. The file can contain ascii
text or HTML code. If the file contains text, it will be displayed as a
single paragraph of information on the resultant web page. If the file
contains HTML code, it will be displayed according to the formatting
within the file.

FILE: .linkbar

The ".linkbar" file is a free form text file which can contain URL link
information for the current web page. A ".linkbar" file can exist for
each directory in the hirarchical structure and is displayed instead of
the default URL link information, if it exists. Obviously, in order to
display URL link information, the file must contain the HTML code which
describes the URL links. Since the linkbar is HTML, the web page
designer can create and format the linkbar to appear any way they
choose.

FILE: .forinfo

The ".forinfo" file is a free form text file which can contain
information regarding who to contact about the current web page. A
".forinfo" file can exist for each directory in the hirarchical
structure and is displayed instead of the default information,
if it exists. Usually, the web page designer will want this file to
contain HTML code so that they can create URL links to e-mail addresses
or remote web sites. But the ".forinfo" file does not have to be HTML
code, it can be straight ASCII text. Typically, the file will say
something like "For information regarding this page, contact Joe Blow
(jblow@email.com)".