Installation Guide for kcd
==========================

If you does not have ncurses 1.9.9e (or better) or zlib 1.0.4 (or better),
obtain and install them before start installing kcd.  If you don't have 
root access to install the library, just build the static library.  Step 2
in the installation procedure provide the way to make kcd recognizes those
libraries that you cannot install in the shared location (such as
`/usr/local/lib').

When installing ncurses, you must use the option `--with-shared' in 
ncurses `configure' command.

Due to bugs in earlier versions of ncurses, the ncurses 4.2 is recommended.
The scroll bars will be turned on by default if kcd is built with 
ncurses 4.2.

kcd Installation Procedure:
===========================

Step 1: Decide whether you want to install kcd for every user in your system
	(which will be refered to as `system-wide' installation) or only for
	your account only (will be refered to as `user-specific'
	installation).   The latter is useful if you do not have root access.

Step 2: Check if the system has the right versions of ncurses and zlib
	installed in standard locations (like `/usr/lib' or `/usr/local/lib' 
	for libraries and `/usr/includes' or `/usr/local/include' for 
	include files).  If they are already installed, proceed the next
	step.

	If not, you will have to build your own copy.  If you do not have
	root access in order to install those libraries in the standard
	directories, you can libraries in directories `../lib' and 
	include files in directories `../include' relative to kcd source
	directory.  Configure script will automatically detect this and
	use them instead of the ones in standard locations.  After you have 
	obtained and built those missing libraries, place them in the 
	directories mentioned above.  Include file needed for zlib is 
	`zlib.h' and ncurses are `curses.h', `unctrl.h', etc. depending on 
	the version of ncurses.  Library file for zlib is `libz.a' 
	and ncurses is `libncurses.a'.  Note that only static libraries in 
	`../lib' are recognized.

Step 3: For system-wide installation:

	   By default kcd will be installed in
	   - `/usr/bin'		if former kcd installation was in /usr/bin
	   - `/usr/local/bin'	if this is your first installation
				or former installation was in /usr/local/bin

	   Type `./configure' (do not type the enclosing quotes) if you want 
	   to install kcd in the default directory shown above

	   or

	   `./configure --prefix=PREFIX' if you want to install kcd in the
	   directory `PREFIX/bin'.  For example, if you want to install to
	   `/usr/bin', type `./configure --prefix=/usr'.

	For user-specific installation:

	   Type `./configure' (do not type the enclosing quotes).
	   kcd will only install in the directory `kcd-bin' inside
	   your home directory

Step 4: Create kcdmain executable by typing `make'.  If you have any error 
	during compiling the program, refer to the Troubleshooting Section
	at the end of this file.

Step 5 (Optional):If you do not want to keep debugging information,
	type `make strip'.

Step 6: For kcd 1.0.0 users
		Remove any lines in `/etc/profile' and `/etc/csh.login' 
		previously added for invoking kcd.  Then proceed the next
		step.

	For kcd 2.0.0 or higher users
		Proceed the next step.

	For new users
		Proceed the next step.

Step 7: For system-wide installation:

	   Type `make install'.  The script will automatically do the
	   following:

	   - Copy `kcdmain' and `kcdscr' to `/usr/bin' directory or
	     the directory `PREFIX/bin' specified in the configure
	     command line.

	   - If the directory `/etc/profile.d' exists:

	     1. Copy `kcd.sh.init' to `/etc/profile.d/kcd.sh'.
	     2. Copy `kcd.csh.init' to `/etc/profile.d/kcd.csh'.
	     3. If `/etc/zprofile' exists, also copy `kcd.sh.init' to
		`/etc/profile.d/kcd.zsh'.

	     Otherwise:

	     1. Copy `kcd.sh.init' and `kcd.csh.init' to `/etc' 
		directory
	     2. Add the following lines to `/etc/profile' and 
		`/etc/zprofile' if exists.

			# For KCD
			. /etc/kcd.sh.init

	     3. Add the following lines to `/etc/csh.login'.

			# For KCD
			source /etc/kcd.csh.init

	For user-specific installation:

	   Type `make installuser'.  The script will
	
	   - create a directory `kcd-bin' in your home directory
	   - copy `kcdmain' and `kcdscr' to `kcd-bin' directory
	   - create .profile and .login if they do not exist
	   - add the following lines to `.profile'.

			# For KCD
			. (your home dir. name)/kcd-bin/kcd.sh.userinit

	   - add the following lines to `.login'.

			# For KCD
			source (your home dir. name)/kcd-bin/kcd.csh.userinit

	   - if your login shell is zsh, add the following lines to
	     `.zprofile'.

			# For KCD
			. (your home dir. name)/kcd-bin/kcd.sh.userinit


	Note:

	The script added was tested under bash, tcsh, ash, zsh and pdksh.
	If you use other shells, you may have to modify to make it works.
	You should also leave the string `For KCD' inside the comment 
	generated by `make installuser' intact.  The string is used as a 
	marker so that any future kcd installation will not touch these 
	files again.

Step 8: Copy `README' and/or `kcd.1' somewhere for your reference.  

	If you use system-wide installation, `kcd.1' is automatically 
	installed into `/usr/man/man1' or `/usr/local/man/man1' for you.

Step 9: If you want to skip some directories from being scanned and
	displayed, create `/etc/kcd.conf' (that effects all users) or a
	private `.kcd.conf' in your home directory (that effects only your
	account).   Following is a sample content of such file:

		SkipDir = "/cdrom"
		SkipDir = "/dosc"

	Here subdirectories inside `/cdrom' and `/dosc' are not scanned and
	stored.  Note that `/dev' and `/proc' are always skipped even it is 
	not specified in `/etc/kcd.conf' or `.kcd.conf'.

	Note to users of kcd 3.1.0 or older:  The old-style skipdir command 
	(No blank allowed inside the command, and the directory name is not 
	quoted) still works with current and all future version of kcd.  It 
	is now considered obsoleted.  A warning message will be printed on 
	the screen if it is encountered.

	For more information about configuration commands, read the README
	file.

Step 10:Logout and login again.  Type `kcd' at your prompt.  You should see 
	a graphical display of directory tree.   kcd may have to scan all 
	directories (except the ones specified in Step 9) in your system 
	(if you have not installed and run kcd before or if the format of
	directory tree file saved by kcd is changed from the previously
	installed version) before displaying the directory tree.   Press 
	F10 to exit.

	If you want to rescan directory to reflect changes at any time later,
	just type `kcd -r' (normal mode) or `kcd -rq' (for quiet mode).


Troubleshooting
===============

- Compilation fails

	One common problem is that ncurses shared library is old compare to 
static library.  That because you forgot use the option `--with-shared' in 
ncurses `configure' command.  Follow the steps below to force kcd to be 
linked to static library.

	1 In kcd directory, type `rm config.cache'.

	2 If `libncurses.a' is in either `/usr/local/lib' or `/usr/lib', 
	  restart Step 3 with the option `--with-static-ncurses'
	  added to configure command.  Note that configure looks for
	  libncurses.a in /usr/local/lib before /usr/lib.

	  Otherwise restart Step 3 with the option
	  `--with-static-ncurses' and specify the directory name that 
	  contains libncurses.a as an argument.  For example, when your 
	  ncurses static library is in /mydir/lib, type

		./configure --with-static-ncurses=/mydir/lib

- During login, it cannot find one of the libraries used by kcd

	If you are using csh or tcsh, look for one of the following files:

		/etc/kcd.csh.init, /etc/profile.d/kcd.csh
		or ~/kcd-bin/kcd.csh.userinit

	and modify this file to set the environment variable 
	LD_LIBRARY_PATH to the directory containing the libraries.

	If you are using other shells, look for one of the following files
	instead:

		/etc/kcd.sh.init, /etc/profile.d/kcd.sh
		or ~/kcd-bin/kcd.sh.userinit

- When running kcd, it cannot find terminfo database or open the terminal

	If you are using csh or tcsh, look for one of the following files:

		/etc/kcd.csh.init, /etc/profile.d/kcd.csh
		or ~/kcd-bin/kcd.csh.userinit

	and modify this file to set the environment variable 
	TERMINFO to the directory containing the terminfo database.

	If you are using other shells, look for one of the following files
	instead:

		/etc/kcd.sh.init, /etc/profile.d/kcd.sh
		or ~/kcd-bin/kcd.sh.userinit
