kshWeb

kshEngine Users Manual

kshWeb Home | ksh Applications, Tools, Utilities | Obtain Korn Shell | Shell News Groups | Publications | Links Korn Shell Jobs | Tip-O-The-Day | Visitor Supplied Scripts | GuestBook | Registration and Download | MicroEMACS

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:

1. Header information. Contains the web site title.
2. Link bar. Contains user defined URLs.
3. Search box
4. Category List. Contains a list of sub-directories in the current directory
5. Search Results. Only exists after performing a search.
6. Item list. Contains a list of files in the current directory.
7. Link bar. Same as above
8. 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)".

FILE: engine.cgi

FILE: title.cgi

FILE: linkbar.cgi

FILE: forinfo.cgi

FILE: indexform.cgi

FILE: addindex.cgi

FILE: delindex.cgi

FILE: sortindex.cgi

kshWeb Home | ksh Applications, Tools, Utilities | Obtain Korn Shell | Shell News Groups | Publications | Links Korn Shell Jobs | Tip-O-The-Day | Visitor Supplied Scripts | GuestBook | Registration and Download | MicroEMACS